Skip to content

Commit f12db36

Browse files
devalogdevalog
committed
add npm publishing guide
1 parent 328644b commit f12db36

File tree

1 file changed

+251
-3
lines changed

1 file changed

+251
-3
lines changed

‎fern/products/sdks/overview/typescript/publishing-to-npm.mdx‎

Lines changed: 251 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,256 @@
11
---
22
title: Publishing to NPM
3-
description: How to publish the Fern Typescript SDK to NPM.
3+
description: How to publish the Fern Typescript SDK to npm.
44
---
55

6-
# Publishing to NPM
6+
Publish your public-facing Fern Typescript SDK to the [npm registry](https://www.npmjs.com/). Once you've followed the steps on this page to connect your npm account to your SDK, Fern will automatically publish the latest version of your SDK.
77

8-
Learn how to publish your Fern Typescript SDK to the NPM registry.
8+
<Info>This guide assumes that you've already generated a TypeScript SDK by following the instructions in [TypeScript Quickstart](quickstart.mdx).</Info>
9+
10+
## Configure your GitHub integration
11+
12+
1. Create a new GitHub repository for your SDK, if you haven't done so already.
13+
1. Install the [Fern GitHub App](https://github.com/apps/fern-api) on your repository.
14+
1. Add your TypeScript SDK files (`fern` and `sdks` folders) to your repository.
15+
16+
17+
## Configure `generators.yml`
18+
19+
<Steps>
20+
21+
<Step title="Run `fern add <generator>`">
22+
23+
Navigate to your `generators.yml`. Your `generators.yml` lives inside of your `fern` folder and contains all the configuration for your Fern generators.
24+
25+
In order to generate the SDK, add the generator to your `generators.yml` using the `fern <add>` command:
26+
27+
28+
```bash
29+
fern add fern-typescript-node-sdk --group ts-sdk
30+
```
31+
32+
Once the command completes, you'll see a new group created in your `generators.yml`:
33+
34+
```yaml {1-3}
35+
groups:
36+
...
37+
ts-sdk:
38+
generators:
39+
- name: fernapi/fern-typescript-node-sdk
40+
version: 1.0.0
41+
output:
42+
location: local-file-system
43+
path: ../sdks/typescript
44+
```
45+
46+
<Info>Here are the [latest versions of each generator](https://github.com/fern-api/fern?tab=readme-ov-file#-generators).</Info>
47+
48+
</Step>
49+
50+
<Step title="Configure `output` location">
51+
52+
Next, change the output location in `generators.yml` to `npm`:
53+
54+
```yaml title="TypeScript" {6-7}
55+
groups:
56+
ts-sdk:
57+
generators:
58+
- name: fernapi/fern-typescript-node-sdk
59+
version: 1.0.0
60+
output:
61+
location: npm
62+
63+
```
64+
</Step>
65+
66+
<Step title="Add a unique package name">
67+
68+
Your package name must be unique in the npm repository, otherwise releasing your SDK to npm will fail. Update your package name if you haven't done so already:
69+
70+
71+
```yaml title="TypeScript" {8}
72+
groups:
73+
ts-sdk:
74+
generators:
75+
- name: fernapi/fern-typescript-node-sdk
76+
version: 1.0.0
77+
output:
78+
location: npm
79+
package-name: name-of-your-package
80+
```
81+
82+
</Step>
83+
84+
85+
<Step title="Add repository location">
86+
87+
Add the path to your GitHub repository to `generators.yml`:
88+
89+
```yaml title="TypeScript" {10-11}
90+
groups:
91+
ts-sdk:
92+
generators:
93+
- name: fernapi/fern-typescript-node-sdk
94+
version: 0.9.5
95+
output:
96+
location: npm
97+
package-name: name-of-your-package
98+
github:
99+
repository: your-org/your-repository
100+
```
101+
102+
</Step>
103+
</Steps>
104+
105+
## Create an npm token
106+
107+
<Steps>
108+
109+
<Step title="Log In">
110+
111+
Log into [npm](https://www.npmjs.com/) or create a new account.
112+
113+
</Step>
114+
115+
<Step title="Navigate to Access Tokens">
116+
117+
Click on your profile picture and select **Access Tokens**.
118+
119+
</Step>
120+
121+
<Step title="Generate Token">
122+
123+
1. Click on **Generate New Token**.
124+
1. Select **Classic Token**.
125+
1. Name your token and select **Automation** as the token type.
126+
1. Once finished, click **Generate Token**.
127+
128+
<Frame>
129+
<img src="assets/npm-automation-token.png" alt="Creating NPM Automation Token" />
130+
</Frame>
131+
132+
<Warning>When you click **Generate Token**, you’ll be returned to the **Access Token** dashboard. A box on the top of the dashboard will confirm that your token creation was a success and prompt you to copy your token id. Make sure you save this id, as you'll need to add it to your GitHub repository in the later on.</Warning>
133+
134+
</Step>
135+
</Steps>
136+
137+
## Add NPM and Fern Tokens to your GitHub Tepository
138+
139+
<Info>
140+
Using GitLab? Follow [these steps](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).
141+
</Info>
142+
143+
<Steps>
144+
145+
<Step title="Open Repository">
146+
147+
Open your Fern repository in GitHub.
148+
149+
</Step>
150+
151+
<Step title="Navigate to Actions in Settings">
152+
153+
Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.
154+
155+
<Frame>
156+
<img src="assets/github-secret.png" alt="Adding GitHub Repository Secret" />
157+
</Frame>
158+
159+
You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.
160+
161+
</Step>
162+
163+
<Step title="Add secret for your NPM Token">
164+
165+
1. Select **New repository secret**.
166+
1. Name your secret `NPM_TOKEN`.
167+
1. Add the corresponding token you generated above.
168+
1. Click **Add secret**.
169+
170+
</Step>
171+
172+
<Step title="Generate and Add Secret for your Fern Token">
173+
174+
1. Generate a Fern token by running `fern token` and saving the token id.
175+
1. Select **New repository secret**.
176+
1. Name your secret `FERN_TOKEN`.
177+
1. Add the corresponding token you generated above.
178+
1. Click **Add secret**.
179+
180+
</Step>
181+
182+
</Steps>
183+
184+
## Configure GitHub Actions
185+
186+
<Steps>
187+
<Step title="Update Workflow Action Settings">
188+
189+
Change your workflow permissions to allow GitHub to run workflows:
190+
191+
1. Click on the **Settings** tab in your repository.
192+
1. Navigate to **Actions**. Under **Actions permissions**, select **Allow all actions and reusable workflows**.
193+
1. **Save** your settings. Now GitHub can run the action you just configured.
194+
195+
</Step>
196+
<Step title="Set up a GitHub Action">
197+
198+
Add a GitHub Action to trigger releases for your SDK. Add a new file called `publish-typescript-sdk.yml` (or something similar) to a new `.github/workflows` directory. Your file should look like this:
199+
200+
201+
```yaml title="TypeScript" maxLines=0
202+
name: Publish TypeScript SDK
203+
204+
on:
205+
workflow_dispatch:
206+
inputs:
207+
version:
208+
description: "The version of the TypeScript SDK that you would like to release"
209+
required: true
210+
type: string
211+
212+
jobs:
213+
release:
214+
runs-on: ubuntu-latest
215+
steps:
216+
- name: Checkout repo
217+
uses: actions/checkout@v4
218+
219+
- name: Install Fern CLI
220+
run: npm install -g fern-api
221+
222+
- name: Release TypeScript SDK
223+
env:
224+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
225+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
226+
run: |
227+
fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug
228+
```
229+
230+
The group name in the `run` command (`ts-sdk`) must match the name of your group in `generators.yml`:
231+
232+
```yaml {2}
233+
groups:
234+
ts-sdk:
235+
generators:
236+
- name: fernapi/fern-typescript-node-sdk
237+
version: 1.10.3
238+
output:
239+
location: npm
240+
package-name: name-of-your-package
241+
token: ${NPM_TOKEN}
242+
github:
243+
repository: your-org/your-repository
244+
```
245+
</Step>
246+
</Steps>
247+
248+
## Release your SDK to NPM
249+
250+
At this point, you're ready to generate a release for your SDK. You can do this by either:
251+
* Running `fern generate --version <version>` to regenerate your SDK.
252+
* Manually triggering your SDK generation workflow from your GitHub repository by navigating to **Actions** and selecting your workflow. Once you initiate the workflow, you'll be prompted to enter the version number of your release.
253+
254+
<img alt="GitHub Page" src="assets/sdk-release-action.png" />
255+
256+
When your workflow executes, you'll receive an email from npm notifying you that your SDK has been successfully published!

0 commit comments

Comments
 (0)