What's coming for jsrepo in v3 #629
Replies: 4 comments 4 replies
-
Feature Request:
|
Beta Was this translation helpful? Give feedback.
-
|
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 That would make it possible to detect updates properly. Right now, It would be super helpful if jsrepo could show something like 2. Handling deleted files during updates 3. Installing all blocks at once |
Beta Was this translation helpful? Give feedback.
-
|
The next branch is up! Going to work on getting previews and initial releases up but the code is all in this PR. Important to note that jsrepo.com is not yet supported but will be open sourced and part of this repository! |
Beta Was this translation helpful? Give feedback.
-
|
For anyone moving from v2 you can checkout the Migration Guide or just run: pnpm dlx @jsrepo/migrate v3 |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Let's talk about jsrepo v3
jsrepohas been mostly static for a while now and there's a reason for that. We have been exploring whatjsreposhould be in v3. As we continue work on our vision forjsreponow is the best time to come in and give your thoughts and opinions on whatjsreposhould be.In short we want to make
jsrepomore 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
jsrepoalways seemed like a hacky solution and ended up crowding your root directory. We want to change that injsrepov3...In jsrepo v3 you create a new config by importing
defineConfigfrom jsrepo:jsrepo.config.ts
This allows
jsrepoto 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 ofjsrepov3.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
jsrepobut 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/uithey have introduced a different process. Instead of compiling all the files and items automatically that is done manually by the registry owner.shadcn/uithen 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
registrykeyjsrepowill then resolve any dependencies of the registry items with thejsrepo buildcommand.The
registrykey 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:Once you've defined your registry you can build it using the
jsrepo buildcommand which leads us to our next change...outputs.Outputs
In
jsrepov2 thejsrepo-manifest.jsonfile 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
jsrepov2 to serve it from your website right now it would create thejsrepo-manifest.jsonfile and move all the files it needed to serve the registry to yourpublicdirectory. This has a few downsides...To solve this we are introducing the
outputskey to your registry config.Outputs allow you to customize the way your registry is distributed. Right now we support 2 output modes,
distributedandrepository.shadcn/ui.jsrepov2 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
outputskey of your registry config like so:We are supporting multiple outputs to open up more use cases in the future. We think it might be nice to have a
shadcnoutput plugin that could allow you to distribute your registry with theshadcncli while usingjsrepoto build your registry.Slimming down the CLI
In
jsrepov3 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 thetestcommand 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 addedjsrepo execwithout a lot of thought and it's not something we actually use at all.jsrepo mcp-jsrepowill 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/mcpor something in the future.Language plugins
In
jsrepov2 new language support can only be added by implementing a new language in thejsreporepo. This requires us to add a dependency to a new parser every time we want to add a new language tojsrepo, injsrepov3 we want to solve this by allowing language plugins.Important
To be clear
jsrepowill still support all the languages we currently support inv2out of the box inv3.How it works
You would define a plugin for your language and import it in your
jsrepo.config.tsfile like so:This will allow you to detect dependencies and resolve and install them when adding registry items.
Limitations
jsrepo.config.tsfile (this can be done automatically byjsrepowhen initializing your registry) as a side effect of this zero-config adds are not supported for custom languagesProvider plugins
Provider plugins will allow you to add support for additional providers to
jsrepo. For instance if you wanted to create your own version ofjsrepo.comyou could create a plugin to resolve urls likemyregistry:@ieedan/stdto the right paths in your registry. Or you want to use a different auth scheme than theAuthorizationheader for your private registry.How it works
You would define a plugin for your provider and import it in your
jsrepo.config.tsfile like so:Limitations
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>. Injsrepov3 we will allow users to add items by runningjsrepo add <name>. This should also allow us to improve our compatibility with other tools likeshadcn/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
jsrepov2 if you have a registry item with the same name as another registry item the first registry item found is the one installed. Injsrepov3 we will allow you to select the registry you want to use for the item: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.Plugins
Plugin types
We support the following plugin types:
Plugin naming
We recommend the following naming convention jsrepo plugins:
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:
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 prettierjsrepo.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:
Official plugins
jsrepo will also have official plugins for some common use cases.
Here's a few we will start with:
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 prettierImportant
ALL official plugins will be scoped to
@jsreposo 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.
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:
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
jsrepoforward we can't be held back by backwards compatibility so only registries built with the v3 CLI will be supported.That being said
jsrepov2 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
jsrepov3 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!
Beta Was this translation helpful? Give feedback.
All reactions