azigler / tsdx-react-storybook-starter

TSDX with an opinionated setup for React and Storybook

tsdx-react-storybook-starter

TSDX with an opinionated setup for React and Storybook

Table of Contents

• Background
• Install
• Usage
  • Scripts
  • TSDX
  • Storybook
  • Example
    • Scripts
  • Tips
• Maintainers
• Contributing
• License

Background

This is an opinionated setup for creating a component library. If you’re looking to build a user-facing React app, you should use a tool like create-react-app, razzle, nextjs, gatsby, or react-static instead. This GitHub template repository is a TSDX project generated with React and Storybook. Configurations have been made to simplify building, testing, and publishing TypeScript component libraries to npm. This project uses the following:

• Yarn
• GitHub Actions
  • ci: Continuous integration (linting, testing, and building) on push
  • deploy: Deploy Storybook, /example, and Jest test coverage to GitHub Pages with jamesives/github-pages-deploy-action@v4
  • pull_request: andresz1/size-limit-action and artiomtr/jest-coverage-report-action on pull requests
• TSDX
  • React (v18)
  • TypeScript
  • Parcel (/example directory)
    • $react-dom alias for hot reloading
  • Rollup
    • CJS/ESM/UMD/SystemJS
    • @svgr/rollup
      • SVG components/URLs
    • rollup-plugin-postcss
      • CSS/LESS/SASS/PostCSS/Stylus
      • CSS Modules
    • @rollup/plugin-image
      • GIF/JPG/PNG/WEBP
    • @rollup/plugin-replace
  • Husky
    • pre-commit: yarn prepare
  • ESLint
  • Prettier
  • ai/size-limit
  • Jest
    • eddyerburgh/jest-transform-stub
    • @testing-library/react
    • olavoparno/istanbul-badges-readme
    • Coverage
    • Snapshots
  • Storybook (v6)
    • styleguidist/react-docgen-typescript
    • @storybook/addon-jest
    • @storybook/addon-design-assets
    • @storybook/addon-a11y
    • @storybook/addon-links
    • @storybook/addon-storysource
    • @storybook/addon-essentials
      • Docs
        • MDX
      • Controls
      • Actions
      • Viewport
      • Backgrounds
      • Toolbars
      • Measure
      • Outline
    • Webpack (v5)
      • CSS/LESS/SASS/PostCSS/Stylus
        • plugin-packs/postcss-preset-env
        • postcss/postcss-nested
      • CSS Modules
      • GIF/JPG/PNG/WEBP
      • @svgr/webpack
        • SVG components/URLs

Install

This repository should be used as a GitHub template. Instead of cloning or forking, you should create your own repository via the Use this template button or the GitHub CLI with the following command:

gh repo create YOUR_PROJECT_NAME --clone --template azigler/tsdx-react-storybook-starter

Once you have your repository initialized and cloned locally, install the necessary packages with the following command in the project directory:

yarn install

Usage

Scripts

You can append additional flags to the scripts when you call them. These scripts have only been tested in Yarn.

• badges: Adds badges to README.md for Jest tests
• build: Runs tsdx build to build CommonJS, ESModules, Universal, and SystemJS module formats to the /dist directory
• clean: Cleans up caches, /dist, and /storybook-static here and in /example
• deploy: Runs the test and build scripts then builds and copies Storybook, /example, and Jest test coverage to the /deploy directory
• dev: Runs tsdx watch
• husky: Initializes Husky using a pre-commit hook with yarn husky:prepare
• husky:prepare: Alias for lint, build, test, size, and storybook:build scripts
• lint: Runs tsdx lint recursively in the /src directory with the --fix flag
• size: Runs ai/size-limit using size-limit configurations in package.json
• start: Alias for dev script
• storybook: Starts a Storybook server at http://localhost:6006
• storybook:build: Builds Storybook to the /storybook-static directory
• test: Runs Jest tests recursively found in the /src directory to save results, coverage, and snapshots and then runs the badges script
• test:ci: Alias for test script when executed via ci GitHub Action
• test:watch: Alias for test script that watches for changes

TSDX

The recommended workflow is to use the following command:

yarn dev

This builds your project to the /dist directory and watches to rebuild automatically when any changes are made in the /src directory.

In another terminal, run either Storybook or the Parcel example and start making your changes with hot reloading.

To build your project for publishing, use the following command:

yarn prepare

CommonJS, ESModules, Universal, and SystemJS module formats are built by default. The appropriate paths are configured in package.json and /dist/index.js accordingly.

To learn more about the different scripts available, check out the Scripts section.

Storybook

To start a Storybook development server with hot reloading at http://localhost:6006, use the following command:

yarn storybook

This loads all stories recursively inside the /src directory.

Stories should reference the components as if using the library, similar to the example playground. This means importing from the root project directory, which aliases to the /dist directory.

To build Storybook as a static site to the /storybook-static directory, use the following command:

yarn storybook:build

To preview the Storybook for the main branch of tsdx-react-storybook-starter, click the following badge:

Example

To start a Parcel development server at http://localhost:1234 with hot reloading, use the following command in the /example directory:

yarn dev

The example will import whatever is in the /dist directory, so if you are seeing out-of-date components then make sure TSDX is running in another terminal via yarn dev like recommended above.

To build the example to the /example/dist directory for production, use the following command in the /example directory:

yarn build

To preview the example in the main branch of tsdx-react-storybook-starter, click here.

Scripts

• build: Builds for production to the /example/dist directory
• clean: Cleans up caches and the /example/dist directory
• dev: Starts a development server at http://localhost:1234 with hot reloading
• start: Alias for dev script

Tips

• If you’re new to TypeScript and React, make sure you read the handbook, then check out sw-yx/react-typescript-cheatsheet.

• To get the most out of this repository, be sure to familiarize yourself with TSDX.

• To maintain best practices, use np when publishing to npm.

• Per Palmer Group guidelines, always use named exports. Code split inside your React app instead of your React library.

Maintainers

@azigler

Contributing

Feedback and contributions are encouraged! After reading the Code of Conduct, use the Bug Report and Feature Request issue templates to discuss any bugs or contributions to tsdx-react-storybook-starter. For more information, please read the Contributing Guide.

License

MIT © Andrew Zigler