What's coming for jsrepo in v3

[ieedan]

Let's talk about jsrepo v3

jsrepo has been mostly static for a while now and there's a reason for that. We have been exploring what jsrepo should be in v3. As we continue work on our vision for jsrepo now is the best time to come in and give your thoughts and opinions on what jsrepo should be.

In short we want to make jsrepo more flexible and easier to use. We want to give you more control over your registry and make it easier to add support for new languages and providers.

As things become more solidified we will continue to update this discussion and open source our progress in the coming weeks.

Note

Nothing here is fully decided yet and we would love to hear your feedback!

Some core changes for v3

New js-based unified config

The multiple json config files for jsrepo always seemed like a hacky solution and ended up crowding your root directory. We want to change that injsrepo v3...

In jsrepo v3 you create a new config by importing defineConfig from jsrepo:
jsrepo.config.ts

import { defineConfig } from "jsrepo";

export default defineConfig({
	// ...
});

This allows jsrepo to be more flexible than before, supporting custom languages, transforms, and much much more. We feel that this is a necessary step to accomplish what we want out of jsrepo v3.

That being said while you might expect the new js config to require more manual intervention we have put in the work to make it just as convenient (if not more) than a json based config. It also has some added benefits like not needing to update your schema versions for new features.

Giving up on fully-automated builds

Fully automated builds has been something that has been the biggest selling point for jsrepo but also it's biggest downfall. In the end the system right now is just too hard to understand and requires a lot of gymnastics to really make work properly on more complex projects.

If you've kept up with shadcn/ui they have introduced a different process. Instead of compiling all the files and items automatically that is done manually by the registry owner. shadcn/ui then detects dependencies and links stuff together with the build command.

We feel this is the right approach to give registry owners the most control over their registry.

That being said we are going to introduce our own touches to make it a bit more ergonomic...

How it works

When defining your registry config you will define it under the registry key jsrepo will then resolve any dependencies of the registry items with the jsrepo build command.

import { defineConfig } from "jsrepo";

export default defineConfig({
	// ...
	registry: {
		name: "@jsrepo/playground",
		items: [
			{
				name: "print",
				files: [
					{
                        // path to a specific file
						path: "./src/registry/print.ts",
					},
				],
			},
            {
				name: "math",
				files: [
					{
                        // path to a folder (will include all contained files)
						path: "./src/registry/math",
					},
				],
			},
		],
	},
});

The registry key can be a single registry object or an array of registry objects. It also accepts a function that returns a registry object or an array of registry objects allowing you to dynamically generate your registry config.

Type definition for registry:

export type Config = {
	// ...
	registry:
		| MaybeGetterAsync<RegistryConfig, RegistryConfigArgs>
		| MaybeGetterAsync<RegistryConfig, RegistryConfigArgs>[]
		| RegistryConfig
		| RegistryConfig[];
};

Once you've defined your registry you can build it using the jsrepo build command which leads us to our next change... outputs.

Outputs

In jsrepo v2 the jsrepo-manifest.json file was originally optimized for serving your registry from a repository but often this isn't the most efficient way to serve your registry.

If you were to build your registry with jsrepo v2 to serve it from your website right now it would create the jsrepo-manifest.json file and move all the files it needed to serve the registry to your public directory. This has a few downsides...

1. You have to fetch each file for a registry item individually which causes a lot of concurrent requests.
2. It's much harder for anyone to determine what files are actually needed for a registry item and where to get them.

To solve this we are introducing the outputs key to your registry config.

Outputs allow you to customize the way your registry is distributed. Right now we support 2 output modes, distributed and repository.

• Distributed outputs break your registry items up into json files much like shadcn/ui.
• Repository outputs will use the same process as jsrepo v2 to minimize code duplication when serving from a repository (will only support serving from the root of your repository)

You define your outputs in the outputs key of your registry config like so:

import { defineConfig } from "jsrepo";
import { distributed } from "jsrepo/outputs";

export default defineConfig({
	// ...
	registry: {
		// ...
		outputs: [distributed({ dir: "./public/r" })],
	},
});

We are supporting multiple outputs to open up more use cases in the future. We think it might be nice to have a shadcn output plugin that could allow you to distribute your registry with the shadcn cli while using jsrepo to build your registry.

Slimming down the CLI

In jsrepo v3 we want to slim down the CLI by dropping unnecessary dependencies and commands. We want your feedback on what you use so we can make the best decisions on what to cut.

Deprecated Commands

Note

Again nothing is fully decided so if you use this functionality or think it could still add value let us know!

• jsrepo test - We feel that the test command in it's current form isn't adding a ton of value. While it is really cool to be able to test your registry items we don't think it's worth the bloat.
• jsrepo exec - We added jsrepo exec without a lot of thought and it's not something we actually use at all.
• jsrepo mcp - jsrepo will still support MCP but we think that moving this to a separate package would be a good strategy to reduce the size of the main CLI. Expect to see this under @jsrepo/mcp or something in the future.

Language plugins

In jsrepo v2 new language support can only be added by implementing a new language in the jsrepo repo. This requires us to add a dependency to a new parser every time we want to add a new language to jsrepo, in jsrepo v3 we want to solve this by allowing language plugins.

Important

To be clear jsrepo will still support all the languages we currently support in v2 out of the box in v3.

How it works

You would define a plugin for your language and import it in your jsrepo.config.ts file like so:

import { defineConfig } from "jsrepo";
import { go } from "jsrepo-plugin-go";

export default defineConfig({
	// ...
	registry: {
		// ...
	},
	langs: [go()],
});

This will allow you to detect dependencies and resolve and install them when adding registry items.

Limitations

1. Users must also install and add the language plugin to their jsrepo.config.ts file (this can be done automatically by jsrepo when initializing your registry) as a side effect of this zero-config adds are not supported for custom languages

Provider plugins

Provider plugins will allow you to add support for additional providers to jsrepo. For instance if you wanted to create your own version of jsrepo.com you could create a plugin to resolve urls like myregistry:@ieedan/std to the right paths in your registry. Or you want to use a different auth scheme than the Authorization header for your private registry.

How it works

You would define a plugin for your provider and import it in your jsrepo.config.ts file like so:

import { defineConfig } from "jsrepo";
import { myProvider } from "jsrepo-provider-myprovider";

export default defineConfig({
	// ...
	providers: [myProvider()],
});

Limitations

1. Users must also install and add the provider plugin to their jsrepo.config.ts file

Dropping support for categories

Dropping support for categories will allow us to simplify things a bit more and improve the user experience around adding registry items. Right now users must add items by running jsrepo add <category>/<name>. In jsrepo v3 we will allow users to add items by running jsrepo add <name>. This should also allow us to improve our compatibility with other tools like shadcn/ui.

We think this will remove a lot of mental overhead for users and make it easier to add new items to your registry.

We are also going to improve the experience for conflicting registry items, in jsrepo v2 if you have a registry item with the same name as another registry item the first registry item found is the one installed. In jsrepo v3 we will allow you to select the registry you want to use for the item:

◆  Multiple registries found for button. Please select one:
│  ● button (https://shadcn-svelte.com)
│  ○ button (https://shadcn-svelte-extras.com)
└

Paths now that categories are gone

With categories gone the paths that items are added to your project can be configured by the type of the item. The same way they are in shadcn/ui.

import { defineConfig } from "jsrepo";

export default defineConfig({
	// ...
	registry: {
		// ...
	}),
	paths: {
		components: "$lib/components",
		utils: "$lib/utils",
	}

Plugins

Plugins are another area that we really want your feedback on so please let us know what you think!

Plugin types

We support the following plugin types:

• transform - Allows you to make transformations to the code of registry items before they are added to your project (eg: formatting, templating, etc).
• language - Allows you to add support for a new language.
• provider - Allows you to add custom providers.
• output - Allows you to control the format that your registry is output in.

Plugin naming

We recommend the following naming convention jsrepo plugins:

jsrepo-(transform|language|provider|output)-<name>

We do this for consistency yes, but also to make it easier to add plugins to your config.

Adding plugins

To make it as easy as possible to use plugins jsrepo can automatically install and add plugins to your config by running:

jsrepo config add transform jsrepo-transform-oxfmt
# or
jsrepo config add provider jsrepo-provider-jsr
# or
jsrepo config add language jsrepo-language-go

For example if you wanted to add prettier formatting when installing blocks you could run:

jsrepo config add transform @jsrepo/jsrepo-transform-prettier
# or the shorthand
jsrepo config add transform prettier

jsrepo.config.ts

import { defineConfig } from "jsrepo";
+import prettier from "@jsrepo/jsrepo-transform-prettier";

export default defineConfig({
	registries: ["@ieedan/std"],
+	transforms: [prettier()],
});

Important

Ensure you are exporting your plugin from the default export. Otherwise this won't work.

You will notice that the name of the default export is taken from the package name. We do this by removing the jsrepo-(transform|language|provider|output)- and transforming the rest to camel case. If your package is scoped we remove the first portion of the name and use the second portion to determine the name.

For example:

jsrepo-transform-prettier -> prettier
jsrepo-transform-faster-prettier -> fasterPrettier
@jsrepo/jsrepo-language-go -> go

Official plugins

jsrepo will also have official plugins for some common use cases.

Here's a few we will start with:

• @jsrepo/jsrepo-transform-prettier - A plugin for prettier formatting.
• @jsrepo/jsrepo-transform-biome - A plugin for biome formatting.

You can add official plugins by using the shorthand name of the plugin:

jsrepo config add transform @jsrepo/jsrepo-transform-prettier
# or using the shorthand name
jsrepo config add transform prettier

Important

ALL official plugins will be scoped to @jsrepo so you can rest assured that they are safe to use.

Why have official plugins?

One might make the argument that we should just have official plugins as a part of the jsrepo CLI by default, but there's a reason that we think this is a better approach.

1. It allows us to keep the CLI smaller by having fewer dependencies
2. It allows users to have more control over the versions of the plugins they use
3. It helps us not cheat. We want plugins to be as flexible as possible and to do that we need to use them ourselves.

Plugins as a dependency of your registry

You may also want/need to have certain plugins be automatically installed when users initialize your registry. For example if you want to use a custom language.

You can do this by adding all required plugins to your registry config like so:

import { defineConfig } from "jsrepo";

export default defineConfig({
	// ...
	registry: {
		// ...
		plugins: {
			languages: [{
				package: "jsrepo-language-go",
				version: "1.0.0", // version is optional
				optional: false, // if items can be installed without the plugin make it optional and jsrepo will prompt the user on whether to install it or not
			}],
			providers: , //...
			transforms: , //...
		},
	},
});

Now when users run init any plugins you specified as required will be installed and added to their config automatically.

No backwards compatibility

To really move jsrepo forward we can't be held back by backwards compatibility so only registries built with the v3 CLI will be supported.

That being said jsrepo v2 will continue to work with registries built with the v2 CLI. So you can continue to use your old registries with the v2 CLI.

Conclusion

We think jsrepo v3 should improve upon the ideas in v2 and give registry owners and users alike far more flexibility over their projects.

We are excited to hear your feedback and hopefully have a beta version for you all to try soon!

[SikandarJODD]

Feature Request: strict mode for import validation

Hey! I'd like to propose adding a strict boolean field to the manifest.

The Problem

When a file has 10+ imports from various sources, it's tedious to manually track and add all those imported files to the manifest.

Proposed Solution

Add a strict field with two modes:

• strict: false (default) - Let me add files without worrying about their imports. Quick and flexible!
• strict: true - Enforce that all imported files must be in the manifest. Keeps everything explicit and validated.

Real-World Example

When creating examples with multiple files like page.svelte, +server.ts, and other component files, I don't always want strict checks for every utility file or lib import. I just want to upload the example files quickly and let developers know upfront (via strict: false) that some dependencies might need to be installed separately.

This would make it much easier to share more examples without getting blocked by dependency validation!

Does this sound reasonable? Open to feedback! 😊

[ieedan]

This is something that has been considered but hasn't been documented above. Right now I have a union prop:

dependencyResolution: 'manual' | 'auto'

This would allow you to toggle between resolving dependencies automatically or just ignoring the item completely.

A strict prop could have some unique benefits though and may be a good solution since sometimes you will still want to automatically resolve some deps. It may actually be a cleaner solution than manually ignoring every dep that you didn't include in the registry.

I think if we are going to add a strict prop to the registry config it will be item by item? Maybe we could have an overall option as well but I think it would be better for this to be more granular?

[SikandarJODD]

Item-by-item strict control sounds perfect. It lets me mark example files as strict: false while keeping core files validated.

My preference

Combine both:

• Global dependencyResolution: 'auto' | 'manual'
• Per-item strict: boolean override when needed

This gives flexibility where I need it without affecting the whole file. Thoughts?

[ieedan]

Yeah I think that makes the most sense

[mmailaender]

Great RFC — v3 really looks like it’s solving a lot of the pain points we’ve had with installing the whole registry into user projects 🎉

I’ve got a few questions / suggestions that came to mind while reading:

1. Per-block versioning & update detection
Is v3 also introducing per-block versioning like we discussed some time back?

That would make it possible to detect updates properly. Right now, jsrepo add only shows nothing at the name (if not installed) and (Installed) if the component is installed. Once a registry grows, it becomes pretty tedious to figure out which blocks actually changed.

It would be super helpful if jsrepo could show something like (Update available) when the local version differs from the remote one — ideally even sorting those to the top of the list.

2. Handling deleted files during updates
Will v3 support deleting files from a block?
If a file gets removed in the registry, it would be great if jsrepo also cleaned it up on the user side during an update. Right now, those leftovers just stay around.

3. Installing all blocks at once
Is an “install all” command part of v3?
Something like jsrepo add <registry> --all to install all dependencies from a registry in one go would be super useful — especially for larger registries with many blocks.

[ieedan]

1. Per-block versioning & update detection

We don't currently have any plans to implement this cause we would need some sort of lock file solution or way of knowing the version of each block individually which isn't something we really have a nice solution for just yet

2. Handling deleted files during updates

This really goes hand in hand with number one. Since we don't know the difference between the last version and the current version it's not possible to remove blocks. This could also have unintended consequences like breaking users that may have created their own files.

3. Installing all blocks at once

Yes! This has already been implemented in v3 with the same syntax as above. Additionally it can also install all the blocks from multiple registries:

jsrepo add @ieedan/shadcn-svelte-extras @ai/elements --all

[ieedan]

The next branch is up! Going to work on getting previews and initial releases up but the code is all in this PR.

#634

Important to note that jsrepo.com is not yet supported but will be open sourced and part of this repository!

[ieedan]

For anyone moving from v2 you can checkout the Migration Guide or just run:

pnpm dlx @jsrepo/migrate v3