Skip to content

Commit cfbe55c

Browse files
devalogdevalog
committed
add example folder, update npm publishing guide
1 parent a5cd583 commit cfbe55c

File tree

4 files changed

+175
-126
lines changed

4 files changed

+175
-126
lines changed

‎examples/typescript-sdk/generators.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# This file configures all of your SDKs and should be located at:
2+
# your-parent-repo/fern/generators.yml.
3+
default-group: local
4+
groups:
5+
local:
6+
generators:
7+
- name: fernapi/fern-typescript-sdk
8+
output:
9+
location: local-file-system
10+
path: ../sdks/typescript
11+
version: 2.6.4
12+
# This group configures a TypeScript SDK for npm publishing
13+
ts-sdk:
14+
generators:
15+
- name: fernapi/fern-typescript-sdk
16+
version: 2.6.4
17+
output:
18+
location: npm
19+
package-name: your-unique-package-name
20+
token: ${NPM_TOKEN}
21+
config:
22+
namespaceExport: YourClientName
23+
github:
24+
repository: your-company/ts-sdk
25+
# other generator groups for other SDKs go here

‎examples/typescript-sdk/typescript-publish.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Add this file as: your-parent-repo/.github/workflows/typescript-publish.yml
2+
# This workflow should be in the same repository as your generators.yml, which
3+
# should point to the repository containing your TypeScript SDK code.
4+
5+
name: Publish TypeScript SDK
6+
7+
on:
8+
# Manually trigger a release from the GitHub UI. Triggering this workflow kicks
9+
# off the npm publishing process from your TypeScript SDK repository.
10+
workflow_dispatch:
11+
inputs:
12+
version:
13+
description: "The version of the TypeScript SDK that you would like to release"
14+
required: true
15+
type: string
16+
17+
jobs:
18+
release:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout repo
22+
uses: actions/checkout@v4
23+
24+
- name: Install Fern CLI
25+
run: npm install -g fern-api
26+
27+
- name: Release TypeScript SDK
28+
env:
29+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
30+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
31+
run: |
32+
fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug

‎fern/products/sdks/github-setup.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Fern recommends a parent-child repository structure containing:
1414

1515
```bash
1616
├─ company-repo # Parent repository
17+
│ ├─ .github.workflows # Contains publishing workflows for all SDKs
1718
│ └─ fern/
1819
│ ├─ fern.config.json # Root-level config
1920
│ ├─ generators.yml # References child repos
@@ -89,7 +90,7 @@ Each SDK has its own repository with the following structure:
8990

9091
```bash
9192
typescript-sdk-repo/ # Individual SDK repository
92-
├─ .github/workflows/ # Publishing workflows
93+
├─ .github/workflows/ # Generated by Fern
9394
├─ scripts/
9495
├─ src/
9596
├─ tests/

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

Lines changed: 116 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -14,92 +14,91 @@ you'll have a versioned package published on npm.
1414
<Info>
1515
This page assumes that you have:
1616

17-
* An initialized `fern` folder on your local machine. See [Set up the `fern`
17+
* An initialized `fern` folder. See [Set up the `fern`
1818
folder](/sdks/overview/quickstart).
19-
* A GitHub repository for your TypeScript SDK. See [Set up your GitHub structure](/sdks/overview/github).
19+
* A GitHub repository for your TypeScript SDK. See [Project structure](/sdks/overview/github).
2020
* A TypeScript generator group in `generators.yml`. See [TypeScript
2121
Quickstart](quickstart#add-the-sdk-generator).
2222

2323
</Info>
2424

2525
## Configure `generators.yml`
2626

27-
<Steps>
27+
<Note>Your `generators.yml` [should live in your parent repository](/sdks/overview/github) (or on your local machine), not the repository that contains your TypeScript SDK code.</Note>
2828

29-
<Step title="Configure `output` location">
29+
<Steps>
30+
<Step title="Configure `output` location">
3031

3132
In the `group` for your TypeScript SDK, change the output location in from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry:
3233

33-
```yaml {6-7}
34-
groups:
35-
ts-sdk: # Group name for your TypeScript SDK
36-
generators:
37-
- name: fernapi/fern-typescript-sdk
38-
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
39-
output:
40-
location: npm
34+
```yaml {6-7} title="generators.yml"
35+
groups:
36+
ts-sdk: # Group name for your TypeScript SDK
37+
generators:
38+
- name: fernapi/fern-typescript-sdk
39+
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
40+
output:
41+
location: npm
42+
```
4143

42-
```
43-
</Step>
44+
</Step>
4445

45-
<Step title="Add a unique package name">
46+
<Step title="Add a unique package name">
4647

47-
Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail. Update your package name if you haven't done so already:
48+
Your package name must be unique in the npm repository, otherwise publishing your SDK to npm will fail.
4849

50+
```yaml {8} title="generators.yml"
51+
groups:
52+
ts-sdk:
53+
generators:
54+
- name: fernapi/fern-typescript-sdk
55+
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
56+
output:
57+
location: npm
58+
package-name: your-package-name
59+
```
4960

50-
```yaml {8}
51-
groups:
52-
ts-sdk:
53-
generators:
54-
- name: fernapi/fern-typescript-sdk
55-
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
56-
output:
57-
location: npm
58-
package-name: your-package-name
59-
```
60-
61-
</Step>
61+
</Step>
6262

6363
<Step title="Configure `namespaceExport`">
6464

65-
The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`).
66-
67-
68-
```yaml {9-10}
69-
groups:
70-
ts-sdk:
71-
generators:
72-
- name: fernapi/fern-typescript-sdk
73-
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
74-
output:
75-
location: npm
76-
package-name: your-package-name
77-
config:
78-
namespaceExport: YourClientName # must be PascalCase
79-
```
80-
81-
</Step>
82-
83-
<Step title="Add repository location">
84-
85-
Add the path to your GitHub repository to `generators.yml`, if you haven't already:
86-
87-
```yaml {11-12}
88-
groups:
89-
ts-sdk:
90-
generators:
91-
- name: fernapi/fern-typescript-sdk
92-
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
93-
output:
94-
location: npm
95-
package-name: your-package-name
96-
config:
97-
namespaceExport: YourClientName
98-
github:
99-
repository: your-org/company-typescript
100-
```
101-
102-
</Step>
65+
The `namespaceExport` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`).
66+
67+
```yaml {9-10} title="generators.yml"
68+
groups:
69+
ts-sdk:
70+
generators:
71+
- name: fernapi/fern-typescript-sdk
72+
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
73+
output:
74+
location: npm
75+
package-name: your-package-name
76+
config:
77+
namespaceExport: YourClientName # must be PascalCase
78+
```
79+
80+
</Step>
81+
82+
<Step title="Add repository location">
83+
84+
Add the path to the GitHub repository containing your TypeScript SDK:
85+
86+
```yaml {11-12} title="generators.yml"
87+
groups:
88+
ts-sdk:
89+
generators:
90+
- name: fernapi/fern-typescript-sdk
91+
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
92+
output:
93+
location: npm
94+
package-name: your-package-name
95+
config:
96+
namespaceExport: YourClientName
97+
github:
98+
repository: your-org/company-typescript
99+
```
100+
101+
</Step>
103102
</Steps>
104103

105104
## Generate an npm token
@@ -169,7 +168,7 @@ Choose how you want to authenticate and publish your SDK to npm. You can use Git
169168
<AccordionGroup>
170169
<Accordion title="Release via a GitHub workflow (recommended)">
171170

172-
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your repository.
171+
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your parent repository.
173172

174173
<Steps>
175174
<Step title="Set up authentication">
@@ -204,81 +203,75 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action
204203
organization listed in `fern.config.json`.
205204
1. Click **Add secret**.
206205

207-
<Frame>
208-
<img src="assets/npm-token-secret.png" alt="NPM_TOKEN secret" />
209-
</Frame>
206+
</Step>
207+
<Step title="Configure npm authentication token">
208+
209+
Add `token: ${NPM_TOKEN}` to `generators.yml`.
210210

211+
```yaml {9} title="generators.yml"
212+
groups:
213+
ts-sdk:
214+
generators:
215+
- name: fernapi/fern-typescript-sdk
216+
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
217+
output:
218+
location: npm
219+
package-name: name-of-your-package
220+
token: ${NPM_TOKEN}
221+
config:
222+
namespaceExport: YourClientName
223+
github:
224+
repository: your-org/your-repository
225+
```
211226
</Step>
212227
<Step title="Set up a new workflow">
213228

214-
In your repo, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Set up a CI workflow that automatically publishes on tagged pushes:
229+
Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this:
215230

216231
```yaml title=".github/workflows/publish.yml" maxLines=0
217232
name: Publish TypeScript SDK
218233

219-
on: [push]
234+
on:
235+
workflow_dispatch:
236+
inputs:
237+
version:
238+
description: "The version of the TypeScript SDK that you would like to release"
239+
required: true
240+
type: string
220241

221242
jobs:
222-
compile:
223-
runs-on: ubuntu-latest
224-
225-
steps:
226-
- name: Checkout repo
227-
uses: actions/checkout@v3
228-
229-
- name: Set up node
230-
uses: actions/setup-node@v3
231-
232-
- name: Compile
233-
run: yarn && yarn build
234-
235-
test:
243+
release:
236244
runs-on: ubuntu-latest
237-
238245
steps:
239246
- name: Checkout repo
240-
uses: actions/checkout@v3
247+
uses: actions/checkout@v4
241248

242-
- name: Set up node
243-
uses: actions/setup-node@v3
249+
- name: Install Fern CLI
250+
run: npm install -g fern-api
244251

245-
- name: Compile
246-
run: yarn && yarn test
247-
248-
publish:
249-
needs: [ compile ]
250-
if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
251-
runs-on: ubuntu-latest
252-
steps:
253-
- name: Checkout repo
254-
uses: actions/checkout@v3
255-
- name: Set up node
256-
uses: actions/setup-node@v3
257-
- name: Install dependencies
258-
run: yarn install
259-
- name: Build
260-
run: yarn build
261-
262-
- name: Publish to npm
263-
run: |
264-
npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN}
265-
if [[ ${GITHUB_REF} == *alpha* ]]; then
266-
npm publish --access public --tag alpha
267-
elif [[ ${GITHUB_REF} == *beta* ]]; then
268-
npm publish --access public --tag beta
269-
else
270-
npm publish --access public
271-
fi
252+
- name: Release TypeScript SDK
272253
env:
254+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
273255
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
256+
run: |
257+
fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug
274258
```
275-
</Step>
276-
<Step title="Trigger a release">
259+
<Note>
260+
You can alternatively configure your workflow `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example.
261+
</Note>
262+
</Step>
263+
264+
<Step title="Run your workflow">
265+
266+
Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**.
267+
268+
This regenerates your SDK, tags the new release with the version number you specified, and initiates a Fern-generated publishing workflow in your TypeScript SDK repository that publishes your release to npm.
277269

278-
To trigger a release, create and push a git tag to your repository. The workflow will automatically run and publish your package to npm.
270+
<Frame>
271+
<img src="assets/ts-sdk-release-action.png" alt="Running TS publish workflow" />
272+
</Frame>
279273

280-
Once your workflow completes, log back into npm and
281-
navigate to **Packages** to see your new release.
274+
Once your workflow completes, log back into npm and navigate to **Packages** to see your new release.
282275

283276
</Step>
284277
</Steps>
@@ -305,8 +298,6 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action
305298
github:
306299
repository: your-org/your-repository
307300
```
308-
309-
When you regenerate your release, Fern will automatically create a workflow in your repository called `.github/workflows/ci.yml` that will automatically publish your release to npm. For an example, see Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml)
310301
</Step>
311302
<Step title="Set npm environment variable">
312303

@@ -318,7 +309,7 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action
318309

319310
</Step>
320311
<Step title="Regenerate your SDK">
321-
312+
Regenerating your SDK tags the new release with the version number you specified and initiates a Fern-generated publishing workflow in your TypeScript SDK repository that publishes your release to npm.
322313

323314
```bash
324315
fern generate --group ts-sdk --version <version>

0 commit comments

Comments
 (0)