jsrepo

v1.0.0
GitHub

Registry Setup

Create your own registry to share your code.

To create a registry start by creating a new GitHub, GitLab, or BitBucket repository.

jsrepo looks at the directories in your project to determine which blocks to add the the jsrepo-manifest.json file. Because of this you need to follow a specific file structure.

root ├── package.json ├── ... └── ├── │ ├── .(ts|js|tsx|jsx|svelte) │ └── │ ├── │ └── └──

You will need to create a folder that will have the block categories (`blocks` above).

Inside this folder you add your categories ex: (utils, components, etc.).

Inside your categories folders you add the code for your blocks. You can either add the block code as a single file directly inside the category or you can create a folder that contains the files for the block.

When adding blocks users will access your blocks by specifying <category>/<name>.

When you are done your file structure might look something like this:

root ├── package.json ├── ... └── blocks └── utils ├─── print.ts └─── math ├─── add.ts └─── subtract.ts

Once you have setup all you files run you'll want to setup a build script to build your blocks into a jsrepo-manifest.json.

The easiest way to do this is to use the CLI:

npx jsrepo init --registry
┌ jsrepo v1.15.1 │ ◇ Where are your blocks located? │ ./src │ ◇ Add another blocks directory? │ No │ ◇ Create a `jsrepo-build-config.json` file? │ Yes │ ◇ Added `build:registry` to scripts in package.json │ ◇ Created `jsrepo-build-config.json` │ ├ Next Steps ────────────────────────────────────────────────┐ │ │ │ 1. Add categories to `./src`. │ │ 2. Run `npm run build:registry` to build the registry. │ │ │ ├──────────────────────────────────────────────────────────────┘ │ └ All done!

This sets your registry for you based on your answers to the prompts.

Once your done you can execute the build script:

npm run build:registry

After running build the output jsrepo-manifest.json should look something like this.

[ { "name": "utils", // category name "blocks": [ // blocks in the category { "name": "print", // name of the block "directory": "src/utils", // directory containing the files "category": "utils", "tests": false, // whether or not the block has tests "subdirectory": false, // is the block in a subdirectory of it's category "files": [ "print.ts" ], "localDependencies": [], // any dependencies to other blocks "dependencies": [], // any dependencies "devDependencies": [] // any dependencies }, { "name": "print", "directory": "src/utils", "category": "utils", "tests": false, "subdirectory": true, "files": [ "add.ts", "subtract.ts" ], "localDependencies": [ "utils/print" ], "dependencies": [], "devDependencies": [] } ] }, ]

Commit the output jsrepo-manifest.json to a public repository and you should now be able to access your blocks by running:

npx jsrepo add --repo github/<owner>/<repo>

Dependencies

Your blocks can depend on npm packages as well as other blocks in your project.

blocks/utils/math/add.ts

import { print } from "../print"; // another block import color from "chalk"; // npm package const add = (a: number, b: number): number => { print(`result is: ${color.cyan(`${a + b}`)}`) }

If you now add utils/math you will get the following output:

npx jsrepo add utils/math
┌ jsrepo v1.0.0 │ ◇ Retrieved blocks from github// │ ◇ Added github///utils/math │ ◇ Added github///utils/print │ ◇ Would you like to install dependencies? │ Yes │ ◇ Installed chalk │ ├ Next Steps ─────────────────────────────┐ │ │ │ Import the blocks from `src/blocks` │ │ │ ├───────────────────────────────────────────┘ │ └ All done!

Excluding Dependencies

By default in *.svelte and *.vue files importing from 'svelte' or 'vue' will not result in the respective frameworks being added as a dependency.

This is because it's pretty easy to assume anyone adding either of those file types to their project will already have Svelte or Vue installed.

However if you are using a *.jsx based framework we don't assume anything for you.

Instead when running the build command you can provide the --exclude-deps flag:

npx jsrepo build --exclude-deps react next

By providing that flag it tells jsrepo to ignore those dependencies and skip adding them to the manifest file.

Config Files

For some registries you will need the user to have config files such as a tailwind.config.ts or global.css.

You can include these files by configuring them in the jsrepo-build-config.json:

{ "configFiles": [ { "name": "Tailwind Config", "path": "./tailwind.config.ts", "expectedPath": "./tailwind.config.ts", "optional": false } ] }

When users initialize your registry they will be prompted to add or update these config files.

Peer Dependencies

Peer dependencies all you to warn your users when they are using unsupported versions of dependencies they need for your registry to function.

An example of this could be your project using TailwindCSS v3 while waiting to migrate to v4. In the mean time you can setup peer dependencies to warn users that v4 is not yet fully supported.

{ "peerDependencies": { "tailwindcss": { "version": "3.x.x", "message": "Tailwind@v4 is not yet fully supported see: https://github.com/ieedan/jsrepo" }, } }

Examples