Building TS Packages: Anatomy Of A React StoryBook TSDX Project

Yoav Ganbar
Published in
3 min readApr 27, 2021


I’ve been having a really great experience using TSDX to create packages. I use it mostly to create UI packages paired with StoryBook, but it’s great for creating any type of TypeScript packages.

In short, it removes a lot of the friction of configuring all the bits and pieces needed to publish an NPM package and bakes in a lot of optimizations and support for most needs. You can find more information on the project website:

I’ve already written about how fast it is to create a React UI project with StoryBook with TSDX, as well as how to create a React + Typescript + Tailwind Design system. However, I thought it would be worth having this breakdown of what you’ll get when you start off a project.

This is aimed as a reference and an explainer that’ll help you find your feet.

A newly created TSDX project with the react-storybook template will have the following files and directories (excluding node_modules):

note that the files under the dist folder have the project name we put in while bootstrapping. In this case I used post-tsdx-project.

Here’s a breakdown:

  • .github: This folder holds the generated Github actions for the repository, with them you can build a pipeline to automate your workflows like testing, building/bundling, and publishing (to make them work, you will need to push your code to a Github repository).
    main.yml: includes Instructions for the GitHub action on how to build, lint, and your code.
    size.yml: An action that uses size-limit package. In short, it makes sure your package doesn't exceed a set KB size. If your built package is more than the set size, your build fails. By default, it is set to 10KB and can be changed/set by the "size-limit" property in the projects package.json.
  • .gitignore: Any repo that was initiated withgit will have this file. It states what is not part of your repository code.
  • .storybook: Your Storybook configuration folder:
    main.js: This is where the main Storybook configuration lives. It controls the behavior of the Storybook server.
    preview.js: This file is where you configure your story rendering. It can be used for global code that would apply to all your stories.
  • LICENSE: The license of your package, eg. MIT.
  • The information about the project. By default, after bootstrapping the project with TSDX, it'll have all the info about TSDX.
  • dist: This folder includes the bundled output of the project. These are the actual files the would be used by consumers of the package. The files in this folder include minified esm (ES modules) and cjs (Common JS) files, as well as source maps and TypeScript type definitions.
  • example: This folder holds the TSDX playground. There is a separate React app in here which can be used to test out package code, and see how it behaves "out in the wild".
    — The example project is a React app with Parcel as its bundler and it is wired up to work with code from your repo, but also anything else you might want to check with it.
  • package.json: Any NPM package has this file, which describes the metadata and the projects' dependencies.
  • src: The root of the project source code. From this folder, the output of the dsit folder is created.
  • stories: The folder wherein our stories live in. This is where we will build our stories once we write our component's code.
  • test: The folder which holds our test files. In TSDX these are configured to work with Jest.
  • tsconfig.json: The project's TypeScript configuration, which was created and configured for us automatically by TSDX.
  • yarn.lock: This is an auto-generated file that helps keep installs consistent across machines.

That’s it!

Hope this helped you, if it did, please clap, like, and share this with your nearest dev community. 😃



Yoav Ganbar

Father. JavaScript enthusiast. I Love web development. Developer Experience @ Previously: Tech Lead & SW Architect @ Fiverr, Capitolis, Culture Trip