# Getting Started

Learn how to get setup and run your own component registry.

### [Epicenter](https://github.com/EpicenterHQ/epicenter)

[Local-first, open source apps](https://github.com/EpicenterHQ/epicenter)

[Special Sponsor](https://github.com/EpicenterHQ/epicenter)

This guide will walk you through the process of setting up your own component registry.

It assumes you already have a project with components and would like to turn it into a registry.

If you're starting a new registry project, you can use the [registry template](https://github.com/huntabyte/shadcn-svelte/tree/main/registry-template) as a starting point. It's already configured for you.

## [registry.json](#registryjson)

The `registry.json` file is only required if you're using the `shadcn-svelte` CLI to build your registry.

If you're using a different build system, you can skip this step as long as your build system produces valid JSON files that conform to the [registry-item schema specification](https://shadcn-svelte.com/docs/registry/registry-item-json).

### [Add a registry.json file](#add-a-registryjson-file)

Create a `registry.json` file in the root of your project.

registry.json

```json
{
  "$schema": "https://shadcn-svelte.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    // ...
 ]
}
```

This `registry.json` file must conform to the [registry schema specification](https://shadcn-svelte.com/docs/registry/registry-json).

## [Add a registry item](#add-a-registry-item)

### [Create your component](#create-your-component)

Add your first component. Here's an example of a simple `<HelloWorld />` component:

registry/hello-world/hello-world.svelte

```svelte
<script lang="ts">
  import { Button } from "$lib/components/ui/button/index.js";
</script>
<Button>Hello World</Button>
```

**Note:** This example places the component in the `registry/` directory. You can place it anywhere in your project as long as you set the correct path in the `registry.json` file and you follow the `registry/[NAME]` directory structure.

```txt
registry
 hello-world
     hello-world.svelte
```

**Important:** If you're placing your component in a custom directory, make sure it can be detected by Tailwind CSS.

src/routes/layout.css

```css
@source "./registry/@acmecorp/ui-lib";
```

### [Add your component to the registry](#add-your-component-to-the-registry)

To add your component to the registry, you need to add your component definition to `registry.json`.

registry.json

```json
{
  "$schema": "https://shadcn-svelte.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "Hello World",
      "description": "A simple hello world component.",
      "files": [
        {
          "path": "./src/lib/hello-world/hello-world.svelte",
          "type": "registry:component"
        }
     ]
    }
  ]
}
```

You define your registry item by adding a `name`, `type`, `title`, `description` and `files`.

For every file you add, you must specify the `path` and `type` of the file. The `path` is the relative path to the file from the root of your project. The `type` is the type of the file.

You can read more about the registry item schema and file types in the [registry item schema docs](https://shadcn-svelte.com/docs/registry/registry-item-json).

## [Build your registry](#build-your-registry)

### [Install the shadcn-svelte CLI](#install-the-shadcn-svelte-cli)

```bash
pnpm i shadcn-svelte@latest
```

```bash
npm i shadcn-svelte@latest
```

```bash
bun install shadcn-svelte@latest
```

### [Add a build script](#add-a-build-script)

Add a `registry:build` script to your `package.json` file.

package.json

```json
{
  "scripts": {
    "registry:build": "pnpm shadcn-svelte registry build"
  }
}
```

### [Run the build script](#run-the-build-script)

Run the build script to generate the registry JSON files.

```bash
pnpm run registry:build
```

```bash
npm run registry:build
```

```bash
bun run registry:build
```

**Note:** By default, the build script will generate the registry JSON files in `static/r` e.g `static/r/hello-world.json`.

You can change the output directory by passing the `--output` option. See the [shadcn-svelte registry build command](https://shadcn-svelte.com/docs/cli#registry-build) for more information.

## [Serve your registry](#serve-your-registry)

You can serve your registry by running the dev server.

```bash
pnpm run dev
```

```bash
npm run dev
```

```bash
bun run dev
```

Your files will now be served at `http://localhost:5173/r/[NAME].json` eg. `http://localhost:5173/r/hello-world.json`.

## [Publish your registry](#publish-your-registry)

To make your registry available to other developers, you can publish it by deploying your project to a public URL.

## [Adding Auth](#adding-auth)

The `shadcn-svelte` CLI does not offer a built-in way to add auth to your registry. We recommend handling authorization on your registry server.

A common simple approach is to use a `token` query parameter to authenticate requests to your registry. e.g. `http://localhost:5173/r/hello-world.json?token=[SECURE_TOKEN_HERE]`.

Use the secure token to authenticate requests and return a 401 Unauthorized response if the token is invalid. The `shadcn-svelte` CLI will handle the 401 response and display a message to the user.

**Note:** Make sure to encrypt and expire tokens.

## [Guidelines](#guidelines)

Here are some guidelines to follow when building components for a registry.

- The following properties are required for the block definition: `name` , `description` , `type` and `files` .
- Make sure to list all registry dependencies in `registryDependencies` . A registry dependency is the name of the component in the registry eg. `input` , `button` , `card` , etc or a URL to a registry item eg. `http://localhost:5173/r/editor.json` - Ideally, place your files within a registry item in `components` , `hooks` , `lib` directories.

## [Install using the CLI](#install-using-the-cli)

To install a registry item using the `shadcn-svelte` CLI, use the `add` command followed by the URL of the registry item.

```bash
pnpm dlx shadcn-svelte@latest add http://localhost:5173/r/hello-world.json
```

```bash
npx shadcn-svelte@latest add http://localhost:5173/r/hello-world.json
```

```bash
bun x shadcn-svelte@latest add http://localhost:5173/r/hello-world.json
```