Welcome

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

1
npm install -g fern-api

Step 2: Initialize Fern

1
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
2
3
4
5
├─ fern.config.json
├─ generators.yml # generators you're using
└─ definition/
  ├─ api.yml  
  └─ 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
service:
  auth: false
  base-path: /movies
  endpoints:
    create: 
      method: POST
      path: /
      request: CreateMovieRequest
      response: MovieId
    get:
      method: GET
      path: /{id}
      path-parameters:
        id: MovieId
      response: Movie
      errors:
        - DoesNotExistError

types:
  MovieId: uuid 

  CreateMovieRequest:
    properties:
      title: string

  Movie:
    properties:
      id: MovieId
      title: string
      rating:
        type: double
        docs: The rating scale is one to five stars

errors:
  DoesNotExistError:
    status-code: 404
    type: MovieId

Step 3: Generate code

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

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

To invoke the generator, run:

1
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: