Quickstart

In this quickstart, we’ll install Fern, initialize a sample API, and generate a TypeScript Node.js SDK. The output files will be downloaded to your local file system.

We’ll use a Fern Definition to describe our endpoints, types, and errors. Alternatively, you can use an OpenAPI specification.

Prerequisites

• Node.js 18 or higher

Step 1: Install Fern

$
npm install -g fern-api

Step 2: Initialize Fern

$
fern init

This will create a fern/ directory which contains a sample API and configuration. This generally lives in your backend repo, but you can also have an independent repo dedicated to your API (like Seam’s).

1
├─ fern.config.json
2
├─ generators.yml # generators you're using
3
└─ definition/
4
  ├─ api.yml  
5
  └─ imdb.yml # endpoints, types, and errors

The example API we’ll use is inspired by IMDb (International Movie Database). We’ll see an endpoint for creating and retrieving a Movie.

1
service:
2
  auth: false
3
  base-path: /movies
4
  endpoints:
5
    create: 
6
      method: POST
7
      path: /
8
      request: CreateMovieRequest
9
      response: MovieId
10
    get:
11
      method: GET
12
      path: /{id}
13
      path-parameters:
14
        id: MovieId
15
      response: Movie
16
      errors:
17
        - DoesNotExistError
18
19
types:
20
  MovieId: uuid 
21
22
  CreateMovieRequest:
23
    properties:
24
      title: string
25
26
  Movie:
27
    properties:
28
      id: MovieId
29
      title: string
30
      rating:
31
        type: double
32
        docs: The rating scale is one to five stars
33
34
errors:
35
  DoesNotExistError:
36
    status-code: 404
37
    type: MovieId

Step 3: Generate code

By default, generators.yml contains the TypeScript Node.js generator.

1
default-group: local
2
groups:
3
  local:
4
    generators:
5
      - name: fernapi/fern-typscript-node-sdk
6
        version: 0.x.x
7
        output:
8
          location: local-file-system
9
          path: ../generated/sdks/typescript

To invoke the generator, run:

$
fern generate

By default, Fern runs the generator in the cloud, compiles your API definition into files, and downloads them to your computer. Once complete, you’ll see new files in /generated/sdks/typescript/.

Note: The generated/ directory will be created at the root level of your repository, one level up from the fern/ folder.

What’s next

Congratulations! You installed Fern, initialized a sample API, and generated your first SDK.

As a next step, you can:

• Use an OpenAPI specification
• Define your API as a Fern Definition
• Configure additional code generators
• Publish the Node.js SDK to npm & GitHub paid feature