Skip to content

Commit 7287ec4

Browse files
ieedanieedan
committed
initial (w changesets)
1 parent 1ad62de commit 7287ec4

11 files changed

+3568
-1
lines changed

‎.changeset/bumpy-wings-grow.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"example-typescript": patch
3+
---
4+
5+
chore: changesets

‎.changeset/config.json

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
3+
"changelog": "@changesets/cli/changelog",
4+
"commit": false,
5+
"fixed": [],
6+
"linked": [],
7+
"access": "restricted",
8+
"baseBranch": "main",
9+
"updateInternalDependencies": "patch",
10+
"ignore": [],
11+
"privatePackages": {
12+
"tag": true,
13+
"version": true
14+
}
15+
}

‎.github/workflows/publish.yml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Publish
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
concurrency: ${{ github.workflow }}-${{ github.ref }}
9+
10+
jobs:
11+
release:
12+
name: Build & Publish Release
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: pnpm/action-setup@v4
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: "20"
21+
cache: pnpm
22+
23+
- name: Install dependencies
24+
run: pnpm install
25+
26+
- name: Create Release Pull Request or Publish
27+
id: changesets
28+
uses: changesets/action@v1
29+
with:
30+
commit: "chore(release): version package"
31+
title: "chore(release): version package"
32+
publish: pnpm ci:release
33+
env:
34+
JSREPO_TOKEN: ${{ secrets.JSREPO_TOKEN }}
35+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
36+
NODE_ENV: production

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
node_modules

‎README.md

+310-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,311 @@
11
# example-typescript
2-
A demo to show you how you can deploy your first typescript registry to jsrepo.com.
2+
3+
A demo to show you how you can deploy your first TypeScript registry to jsrepo.com.
4+
5+
Within is an example of an over-engineered calculator to help demonstrate how jsrepo works.
6+
7+
### Relevant Links
8+
9+
- [jsrepo](https://github.com/jsrepojs/jsrepo)
10+
- [jsrepo.com](https://jsrepo.com)
11+
12+
### Prerequisites
13+
14+
- Have an account on [jsrepo.com](https://jsrepo.com)
15+
16+
## Tutorial
17+
18+
In this tutorial we will cover how to build and publish a simple TypeScript registry to [jsrepo.com](https://jsrepo.com).
19+
20+
### 1. Initialize a TypeScript project
21+
22+
Start by initializing a TypeScript project (I will use pnpm for this)
23+
24+
```sh
25+
pnpm init
26+
27+
pnpm install typescript -D
28+
29+
pnpm tsc --init
30+
```
31+
32+
### 2. Create your components
33+
34+
Now lets create some components that we want to share.
35+
36+
Lets create a `./src` directory and within it we can create a `/utils` folder.
37+
38+
Your project should now look something like this:
39+
40+
```plaintext
41+
root
42+
├── /src
43+
│ └── /utils
44+
├── package.json
45+
└── tsconfig.json
46+
```
47+
48+
Now let's add our components.
49+
50+
`calculator.ts`:
51+
52+
```ts
53+
import { Logger } from "./logger";
54+
55+
export class Calculator {
56+
add(a: number, b: number): ArithmeticResult {
57+
return new ArithmeticResult(a + b);
58+
}
59+
60+
subtract(a: number, b: number): ArithmeticResult {
61+
return new ArithmeticResult(a - b);
62+
}
63+
}
64+
65+
export class ArithmeticResult {
66+
private val: number;
67+
private logger = new Logger();
68+
69+
constructor(result: number) {
70+
this.val = result;
71+
}
72+
73+
print() {
74+
this.logger.success(`The answer is ${this.val}!`);
75+
}
76+
77+
get value() {
78+
return this.val;
79+
}
80+
}
81+
```
82+
83+
`logger.ts`:
84+
85+
```ts
86+
import color from "chalk";
87+
88+
export class Logger {
89+
private logger: typeof console.log;
90+
91+
constructor(logger = console.log) {
92+
this.logger = logger;
93+
}
94+
95+
success(msg: string) {
96+
this.logger(`${color.cyan("[success]")} ${msg}`);
97+
}
98+
99+
failure(msg: string) {
100+
this.logger(`${color.cyan("[failure]")} ${msg}`);
101+
}
102+
}
103+
```
104+
105+
## 3. Prepare the registry for publish
106+
107+
Now that we have our components let's configure `jsrepo` to publish our registry to [jsrepo.com](https://jsrepo.com).
108+
109+
Start by running the init command:
110+
111+
```sh
112+
pnpm dlx jsrepo init --registry
113+
```
114+
115+
When asked _"Where are your blocks located?"_ answer `./src` because that is where our categories are.
116+
117+
Answer yes to _"Configure to publish to jsrepo.com?"_ and then input the name of your registry.
118+
119+
> The name of the registry should be in the format of `@<scope>/<name>`. If you don't already have a scope you can claim one [here](https://jsrepo.com/account/scopes/new).
120+
121+
```plaintext
122+
┌ jsrepo v2.0.0
123+
│
124+
◇ Where are your blocks located?
125+
│ ./src
126+
│
127+
◇ Add another blocks directory?
128+
│ No
129+
│
130+
◇ Configure to publish to jsrepo.com?
131+
│ Yes
132+
│
133+
◇ What's the name of your registry?
134+
│ @example/typescript
135+
│
136+
◇ Added script to package.json
137+
│
138+
◇ Wrote config to `jsrepo-build-config.json`
139+
│
140+
├ Next Steps ─────────────────────────────────────────────────────┐
141+
│ │
142+
│ 1. Add categories to `./src`. │
143+
│ 2. Run `pnpm run release:registry` to publish the registry. │
144+
│ │
145+
├─────────────────────────────────────────────────────────────────┘
146+
│
147+
└ All done!
148+
```
149+
150+
Now your registry should be ready to publish!
151+
152+
## 4. Publish your registry
153+
154+
Now that your registry has been configured to publish to [jsrepo.com](https://jsrepo.com) let's authenticate to the jsrepo CLI.
155+
156+
```sh
157+
jsrepo auth
158+
159+
# or
160+
161+
jsrepo auth --token <...>
162+
```
163+
164+
Once you are authenticated let's do a dry run to make sure we got everything right:
165+
166+
```sh
167+
jsrepo publish --dry-run
168+
```
169+
170+
If all went well you should see:
171+
172+
```plaintext
173+
◆ [jsrepo.com] Completed dry run!
174+
```
175+
176+
See it? Great! Now let's do it for real!
177+
178+
```sh
179+
jsrepo publish
180+
```
181+
182+
And there you go you published your first registry to [jsrepo.com](https://jsrepo.com).
183+
184+
Now you can access your components through the `jsrepo` CLI.
185+
186+
```sh
187+
jsrepo init @example/typescript
188+
189+
jsrepo add # list components
190+
191+
jsrepo add utils/calculator # add individual
192+
```
193+
194+
### 5. Advanced usage
195+
196+
#### Un-listing blocks
197+
198+
Now let's do a few things to improve our registry.
199+
200+
First of all when we run the `jsrepo add` command right now to list our components we see `calculator` and `logger`. Since `logger` is just an internal helper for `calculator` why don't we prevent it from coming up on this list.
201+
202+
We can do this with the `doNotListBlocks` key in our `jsrepo-build-config.json` file:
203+
204+
```jsonc
205+
{
206+
// -- snip --
207+
"doNotListBlocks": ["logger"]
208+
// -- snip --
209+
}
210+
```
211+
212+
Now when we list our blocks only `calculator` will appear.
213+
214+
> Alternatively if we had more internal utils we could use `listBlocks` and only include `calculator` to prevent others from showing up here.
215+
216+
#### Changesets
217+
218+
Another thing you may want to setup if you are publishing a registry to [jsrepo.com](https://jsrepo.com) is [changesets](https://github.com/changesets/changesets).
219+
220+
Changesets are an awesome way to manage the versioning of your registry let's set them up here.
221+
222+
```sh
223+
pnpm install @changesets/cli -D
224+
225+
pnpm changeset init
226+
```
227+
228+
Now that you have changesets initialized let's make a small modification to the `.changeset/config.json` file:
229+
230+
```diff
231+
{
232+
// -- snip --
233+
+ "privatePackages": {
234+
+ "tag": true,
235+
+ "version": true
236+
+ }
237+
}
238+
```
239+
240+
Let's also modify our `package.json` so that our release get's tagged when we publish a new version:
241+
242+
```diff
243+
{
244+
// -- snip --
245+
"scripts": {
246+
+ "release:registry": "jsrepo publish && changeset tag"
247+
}
248+
// -- snip --
249+
}
250+
```
251+
252+
And finally let's modify our `jsrepo-build-config.json` file to use the version from our `package.json`:
253+
254+
> You'll want to make sure that the version in your `package.json` matches the version in your `jsrepo-build-config.json` before continuing.
255+
256+
```diff
257+
{
258+
// -- snip --
259+
+ "version": "package",
260+
// -- snip --
261+
}
262+
```
263+
264+
Finally let's create a workflow so that we can publish a new version of our registry whenever there are changesets.
265+
266+
`.github/workflows/publish.yml`
267+
```yaml
268+
name: Publish
269+
270+
on:
271+
push:
272+
branches:
273+
- main
274+
275+
concurrency: ${{ github.workflow }}-${{ github.ref }}
276+
277+
jobs:
278+
release:
279+
name: Build & Publish Release
280+
runs-on: ubuntu-latest
281+
282+
steps:
283+
- uses: actions/checkout@v4
284+
- uses: pnpm/action-setup@v4
285+
- uses: actions/setup-node@v4
286+
with:
287+
node-version: "20"
288+
cache: pnpm
289+
290+
- name: Install dependencies
291+
run: pnpm install
292+
293+
- name: Create Release Pull Request or Publish
294+
id: changesets
295+
uses: changesets/action@v1
296+
with:
297+
commit: "chore(release): version package"
298+
title: "chore(release): version package"
299+
publish: pnpm ci:release
300+
env:
301+
JSREPO_TOKEN: ${{ secrets.JSREPO_TOKEN }} # !! DON'T FORGET THIS !!
302+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
303+
NODE_ENV: production
304+
```
305+
306+
Now lets create a changeset:
307+
```sh
308+
pnpm changeset
309+
```
310+
311+
Now once we commit our changeset to main changesets will automatically open a PR and version our package for us to create a release.

‎jsrepo-build-config.json

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"$schema": "https://unpkg.com/jsrepo@2.0.0/schemas/registry-config.json",
3+
"name": "@example/typescript",
4+
"version": "package",
5+
"readme": "README.md",
6+
"dirs": ["./src"],
7+
"doNotListBlocks": ["logger"],
8+
"doNotListCategories": [],
9+
"listBlocks": [],
10+
"listCategories": [],
11+
"excludeDeps": [],
12+
"includeBlocks": [],
13+
"includeCategories": [],
14+
"excludeBlocks": [],
15+
"excludeCategories": [],
16+
"preview": false
17+
}

0 commit comments

Comments
 (0)