From 0dfb1f26c3a1c4d602484e403d2f588e6deb42c0 Mon Sep 17 00:00:00 2001 From: Aidan Bleser Date: Mon, 28 Apr 2025 08:37:15 -0500 Subject: [PATCH 1/6] next docs --- src/lib/backend/db/schema.ts | 5 - src/lib/components/icons/index.ts | 2 + .../components/icons/jsrepo-wordmark.svelte | 53 ++++++++ src/lib/components/icons/jsrepo.svelte | 29 +++-- .../site/docs/provider-cards.svelte | 5 + src/lib/docs/cli/publish.md | 69 +++++++++++ src/lib/docs/map.ts | 9 ++ src/lib/docs/registry/providers/jsrepo.md | 115 ++++++++++++++++++ 8 files changed, 274 insertions(+), 13 deletions(-) create mode 100644 src/lib/components/icons/jsrepo-wordmark.svelte create mode 100644 src/lib/docs/cli/publish.md create mode 100644 src/lib/docs/registry/providers/jsrepo.md diff --git a/src/lib/backend/db/schema.ts b/src/lib/backend/db/schema.ts index a2f7875..98baa11 100644 --- a/src/lib/backend/db/schema.ts +++ b/src/lib/backend/db/schema.ts @@ -7,8 +7,3 @@ export const registries = pgTable('registries', { }); export type Registry = typeof registries.$inferSelect; - -export const featuredRegistries = pgTable('featured_registries', { - url: text().notNull(), - created_at: timestamp() -}); diff --git a/src/lib/components/icons/index.ts b/src/lib/components/icons/index.ts index bec42df..d87815b 100644 --- a/src/lib/components/icons/index.ts +++ b/src/lib/components/icons/index.ts @@ -8,6 +8,7 @@ import React from './react.svelte'; import JavaScript from './javascript.svelte'; import Vue from './vue.svelte'; import Jsrepo from './jsrepo.svelte'; +import JsrepoWordmark from './jsrepo-wordmark.svelte'; import GitLab from './gitlab.svelte'; import BitBucket from './bitbucket.svelte'; import Yaml from './yaml.svelte'; @@ -32,6 +33,7 @@ export { JavaScript, Vue, Jsrepo, + JsrepoWordmark, GitLab, BitBucket, Yaml, diff --git a/src/lib/components/icons/jsrepo-wordmark.svelte b/src/lib/components/icons/jsrepo-wordmark.svelte new file mode 100644 index 0000000..535bc2b --- /dev/null +++ b/src/lib/components/icons/jsrepo-wordmark.svelte @@ -0,0 +1,53 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/lib/components/icons/jsrepo.svelte b/src/lib/components/icons/jsrepo.svelte index 4424ab3..e28968b 100644 --- a/src/lib/components/icons/jsrepo.svelte +++ b/src/lib/components/icons/jsrepo.svelte @@ -1,27 +1,40 @@ - - + + + - - + + diff --git a/src/lib/components/site/docs/provider-cards.svelte b/src/lib/components/site/docs/provider-cards.svelte index 11bd7de..a671aed 100644 --- a/src/lib/components/site/docs/provider-cards.svelte +++ b/src/lib/components/site/docs/provider-cards.svelte @@ -4,6 +4,11 @@ import { Server } from '@lucide/svelte'; const providers = [ + { + name: 'jsrepo.com', + icon: Icons.JsrepoWordmark, + href: '/docs/registry/providers/jsrepo' + }, { name: 'GitHub', icon: Icons.GitHub, diff --git a/src/lib/docs/cli/publish.md b/src/lib/docs/cli/publish.md new file mode 100644 index 0000000..c8a3d49 --- /dev/null +++ b/src/lib/docs/cli/publish.md @@ -0,0 +1,69 @@ +--- +title: publish +description: Publish your registry to jsrepo.com. +lastUpdated: 4-28-2025 +--- + +```sh +jsrepo publish +``` + +## Usage + +Publish your registry to [jsrepo.com](https://jsrepo.com): + +```sh +jsrepo publish +``` + +## Options + +### `--private` + +When publishing the first version of the registry make it private. + +#### Usage + +```sh +jsrepo publish --private +``` + +### `--dry-run` + +Test the publish but don't list on jsrepo.com. + +#### Usage + +```sh +jsrepo publish --dry-run +``` + +### `--verbose` + +More verbose logging. (May be used to troubleshoot issues) + +#### Usage + +```sh +jsrepo publish --verbose +``` + +### `--cwd` + +Run the current command on the provided directory absolute or relative. + +#### Usage + +```sh +jsrepo publish --cwd ./sites/docs +``` + +### `-h, --help` + +Help with the command. + +#### Usage + +```sh +jsrepo publish --help +``` diff --git a/src/lib/docs/map.ts b/src/lib/docs/map.ts index 3665fa8..e6ae017 100644 --- a/src/lib/docs/map.ts +++ b/src/lib/docs/map.ts @@ -57,6 +57,10 @@ const tempMap: Record = { title: 'init', slug: 'init' }, + { + title: 'publish', + slug: 'publish' + }, { title: 'test', slug: 'test' @@ -77,6 +81,11 @@ const tempMap: Record = { title: 'Choose a Provider', slug: 'providers', children: [ + { + title: 'jsrepo', + slug: 'jsrepo', + tag: 'New' + }, { title: 'GitHub', slug: 'github' diff --git a/src/lib/docs/registry/providers/jsrepo.md b/src/lib/docs/registry/providers/jsrepo.md new file mode 100644 index 0000000..10c36fa --- /dev/null +++ b/src/lib/docs/registry/providers/jsrepo.md @@ -0,0 +1,115 @@ +--- +title: jsrepo.com +description: How to publish and serve your registry on jsrepo.com. +lastUpdated: 4-28-2025 +--- + +[jsrepo.com](https://jsrepo.com) is the best way to host your registry. It has first class support for semantic versioning and private registries so that you can worry less about hosting and more about shipping. + +## semver + +One of the greatest benefits of hosting your registry on **jsrepo.com** is first class support for [semver](https://semver.org/) (Semantic Versioning). + +While using a git provider with tags is a fine solution for basic versioning needs it's far less secure because tags are mutable. + +With **jsrepo.com** versions are immutable, meaning they will forever point to the same version of the code that you originally specified. + +Versions can be specified for a **jsrepo.com** registry with the same syntax you might see on npm or jsr: +```sh +jsrepo init @ieedan/std@0.0.1 +``` + +**jsrepo** (like npm or jsr) will tag your releases. For instance the latest (non pre-release) version of a registry will be tagged with the `latest` tag. And the latest version of a pre-release will be tagged using it's pre-release label, for instance `1.0.0-next.1` would be tagged with `next`. + +You specify a tagged version with the same syntax: +```sh +jsrepo init @ieedan/std@latest +``` + +## Private registries + +**jsrepo.com** also has first class support for private registries. It's easier than ever to share code with your entire team using **jsrepo.com**. + +Once you have invited your team to an organization on **jsrepo.com** they will be able to access any public or private registries in the scopes owned by that organization with their own PAT. + +## Publishing to jsrepo.com + +To get started with [jsrepo.com](https://jsrepo.com) you will need to sign in using your GitHub account. + +Next claim a scope [here](https://jsrepo.com/account/scopes/new). Scopes are a prefix added to your registry to group related registries together. + +For example: +```sh +@ieedan/std +``` + +Here `@ieedan` is the scope and `std` is the registry name. + +Next you will need to create an access token [here](https://jsrepo.com/account/access-tokens/new). + +With your newly created access token, authenticate to the jsrepo CLI like so: +```sh +jsrepo auth jsrepo --token +``` + +> If you are publishing in a workflow you can use the `JSREPO_TOKEN` environment variable instead. + +### Preparing to publish your registry + +Now that you have authenticated to the jsrepo CLI you are ready to start publishing registries. + +Before we do that however there's a few things we need to do. For starters we need to add the `name` and `version` keys to our `jsrepo-build-config.json` like so. + +```jsonc +{ + "name": "@ieedan/std", + "version": "0.0.1", + // ... +} +``` + +These function similarly to the `name` and `version` keys in a `package.json` and tell **jsrepo.com** the name of the registry as well as what `version` to publish it under. + +#### Registry Metadata + +It's also a good idea to include metadata with your registry if you want it to be easily searchable on **jsrepo.com**. + +This can be done using the `meta` key: +```jsonc +{ + // ... + "meta": { + "authors": ["Aidan Bleser"], + "bugs": "https://github.com/ieedan/std/issues", + "description": "Fully tested and documented TypeScript utilities brokered by jsrepo.", + "homepage": "https://ieedan.github.io/std/", + "repository": "https://github.com/ieedan/std", + "tags": ["typescript", "std", "utilities"] + }, +} +``` + +### Publishing your registry + +Now that your registry is ready to be published let's verify that everything is working correct with the `--dry-run` flag: + +```sh +jsrepo publish --dry-run +``` + +This will check everything and ensure that publishing your registry will succeed. (Even that the version doesn't already exist) + +When you are ready to publish your registry just run: + +```sh +jsrepo publish +``` + +If the publish succeeds you should now be able to add blocks from your registry like so: + +```sh +jsrepo add --repo @ieedan/std # add from list +jsrepo add @ieedan/std/utils/math # add specific block +jsrepo add --repo @ieedan/std@0.0.1 # add specific version +jsrepo add --repo @ieedan/std@latest # add tagged version +``` From ba3051303bd63643454487c67ed8e98138188579 Mon Sep 17 00:00:00 2001 From: Aidan Bleser Date: Mon, 28 Apr 2025 14:12:08 -0500 Subject: [PATCH 2/6] Update publish.md --- src/lib/docs/cli/publish.md | 130 ++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/src/lib/docs/cli/publish.md b/src/lib/docs/cli/publish.md index c8a3d49..6147045 100644 --- a/src/lib/docs/cli/publish.md +++ b/src/lib/docs/cli/publish.md @@ -28,6 +28,26 @@ When publishing the first version of the registry make it private. jsrepo publish --private ``` +### `--name` + +The name of the registry to publish. + +#### Usage + +```sh +jsrepo publish --name @ieedan/std +``` + +### `--ver` + +The version of the registry to publish. + +#### Usage + +```sh +jsrepo publish --ver 0.0.1 +``` + ### `--dry-run` Test the publish but don't list on jsrepo.com. @@ -38,6 +58,116 @@ Test the publish but don't list on jsrepo.com. jsrepo publish --dry-run ``` +### `--dirs` + +The directories containing the categories. Corresponding config key: `dirs` + +#### Usage + +```sh +jsrepo publish --dirs ./src ./blocks +``` + +### `--include-blocks` + +Include only the blocks with these names. Corresponding config key: `includeBlocks` + +#### Usage + +```sh +jsrepo publish --include-blocks math logger +``` + +### `--include-categories` + +Include only the categories with these names. Corresponding config key: `includeCategories` + +#### Usage + +```sh +jsrepo publish --include-categories utils scripts +``` + +### `--exclude-blocks` + +Do not include the blocks with these names. Corresponding config key: `excludeBlocks` + +#### Usage + +```sh +jsrepo publish --exclude-blocks math logger +``` + +### `--exclude-categories` + +Do not include the categories with these names. Corresponding config key: `excludeCategories` + +#### Usage + +```sh +jsrepo publish --exclude-categories utils scripts +``` + +### `--list-blocks` + +List only the blocks with these names. Corresponding config key: `listBlocks` + +#### Usage + +```sh +jsrepo publish --list-blocks math logger +``` + +### `--list-categories` + +List only the categories with these names. Corresponding config key: `listCategories` + +#### Usage + +```sh +jsrepo publish --list-categories utils scripts +``` + +### `--do-not-list-blocks` + +Do not list the blocks with these names. Corresponding config key: `doNotListBlocks` + +#### Usage + +```sh +jsrepo publish --do-not-list-blocks math logger +``` + +### `--do-not-list-categories` + +Do not list the categories with these names. Corresponding config key: `doNotListCategories` + +#### Usage + +```sh +jsrepo publish --do-not-list-categories utils scripts +``` + +### `--exclude-deps` + +Prevent these dependencies from being included in the `jsrepo-manifest.json` file. Corresponding config key: `excludeDeps` + +#### Usage + +```sh +jsrepo publish --exclude-deps svelte react +``` + +### `--allow-subdirectories` + +Allow subdirectories to be built. Corresponding config key: `allowSubdirectories` + +#### Usage + +```sh +jsrepo publish --allow-subdirectories +``` + ### `--verbose` More verbose logging. (May be used to troubleshoot issues) From 11eb146ac15e1da971ccc0ff344c404b3d88c790 Mon Sep 17 00:00:00 2001 From: Aidan Bleser Date: Fri, 2 May 2025 15:12:19 -0500 Subject: [PATCH 3/6] update links --- src/lib/components/site/docs/nav-menu.svelte | 2 +- src/lib/components/site/footer.svelte | 2 +- src/lib/components/site/star-button.svelte | 2 +- src/routes/+layout.server.ts | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lib/components/site/docs/nav-menu.svelte b/src/lib/components/site/docs/nav-menu.svelte index 8e9c20c..92435ad 100644 --- a/src/lib/components/site/docs/nav-menu.svelte +++ b/src/lib/components/site/docs/nav-menu.svelte @@ -73,7 +73,7 @@