Getting Started With Basketry

Code-generation for any language

Photo by Andrea Scully on Unsplash

Basketry is the pluggable, service-oriented code-generation pipeline for any language. Read more about Basketry and view Basketry on Github.

This guide will take you step-by-step through generating a new service, starting with the Swagger pet store example.


If you haven’t yet, go ahead and read Introducing Basketry. It gives a full explanation of what Basketry is and what types of problems it solves. It also covers all of the Basketry-related terms that will show up in the guide, such as Service Definitions, Parsers, Rules, Generators, and Intermediate Representation.

We’ll talk about installing packages and creating and running scripts. This guide assumes that you already have a working knowledge of NPM or Yarn and know how to use your preferred package manager to perform those actions.

Lastly, we will be building our service in Typescript. This guide assumes that you are either familiar with setting up a new project or have access to an existing project. If you want to use the Typescript project scaffolding tool that I personally use for new projects, check out my Yeoman generator.

Initial Setup

Get a Service Definition

Let’s start by downloading an existing Service Definition. offers an example Swagger doc defining an example pet store service: Download that file as swagger.jsonand put it in the root folder of your project.

Install packages

Start by installing the following packages:

  • basketry
  • @basketry/swagger-2
  • @basketry/typescript

The first package contains the Basketry CLI via the basketry command. There are two ways to use the CLI. First, you can pass all of your project options directly to the CLI as arguments. See the README in the repository for details on these arguments. Secondly, you can add a basketry.config.json file in the root of your project, and then just run basketry without any arguments. We will be using a configuration file in this guide.

The second package is the Parser for Swagger 2.0 documents. This package exports a default module that takes the raw Swagger doc and outputs an Intermediate Representation (IR) of the service.

The last package is the Generator that takes the IR and outputs a types.ts file that contains all of the interfaces, types, and enums necessary to implement the pet store service.

Create scripts

Create the following scripts in package.json to run the Basketry CLI:

"scripts": {
"basketry": "basketry",
"watch:basketry": "basketry --watch"

When we run the basketry script, the Basketry CLI will look for a basketry.config.json file to know what parser and generator to use and where to find the Swagger doc. Let’s create that next.

Create a config file

Add the following basketry.config.json file to the root of your project:

"source": "swagger.json",
"parser": "@basketry/swagger-2",
"generators": ["@basketry/typescript"],
"output": "src/petstore"

Let’s walk through what each of those settings does.

First, source lets Basketry know where we want to load our Service Definition from. If you want to rename swagger.json to something else, make sure to also reflect that name change in the config.

Next, parser lets Basketry know what module to use to parse the Swagger doc into IR. The rest of the pipeline doesn’t know that the original Service Definition Language (SDL) was Swagger—the Generators (and Rules when we add them) can work with any source language. For this to work, we need to pick a Parser that understands the SDL, which is why we installed @basketry/swagger-2.

Moving on, generators lets Basketry know how to convert the IR into code files. We can add as many Generators as we want. To start with, we’ll only use @basketry/typescript. We’ll add more later in the guide.

Lastly, output specifies where we want Basketry to put the generated files. Some Generators may write files within subfolders; however, the output folder will be the root directory for all generated content.

Refer to the Basketry wiki for more information about config files.

Generate some code!

Now run the basketry command:

Getting Started With Basketry was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

(Visited 1 times, 1 visits today)