Step‑by‑Step Guide to Building and Publishing a React Component Library with Create‑React‑App, Docz, and Netlify

The article walks through the entire process of building a reusable React component library, starting from project scaffolding with create-react-app (TypeScript template) and ending with deployment of documentation and npm publishing.

Local development environment : Initialize the project with npx create-react-app myapp --typescript , ensure Node >10.15.0, add EXTEND_ESLINT=true to a .env file to enable ESLint, and install node-sass ( npm i node-sass -D ) to compile SCSS.

Project structure : Create a styles folder containing variables.scss , mixins.scss , and index.scss ; under components place each component (e.g., Button ) with its own button.tsx , button.scss , button.mdx , and test file. The tree looks like:

|-styles
|  |-variables.scss
|  |-mixins.scss
|  |-index.scss
|-components
|  |-Button
|    |-button.tsx
|    |-button.scss
|    |-button.mdx
|    |-button.test.tsx
|  |-index.tsx

Build and compile : Add a tsconfig.build.json with appropriate compiler options, then define npm scripts such as "build-ts": "tsc -p tsconfig.build.json" and CSS build script "build-css": "node-sass ./src/styles/index.scss ./dist/index.css" . The final build command is npm run clean && npm run build-ts && npm run build-css , producing dist with compiled JS and CSS.

Local debugging with npm link : In the library folder run npm link , then in the demo project run npm link reactui to create a symlink. Adjust package.json of the library to expose main , module , and types , and add peerDependencies for react and react-dom (>=16.8.0) so the demo uses the same React copy.

Publishing to npm : Log in with npm adduser , verify with npm whoami , then ensure files , dependencies , and peerDependencies are correctly set in package.json . Finally run npm publish (using the official npm registry).

Generating documentation : Choose docz over Storybook for its MDX‑based workflow. Install with npm install docz , add scripts "docz:dev": "docz dev" , "docz:build": "docz build" , and create a doczrc.js file to configure source files, output folder, title, TypeScript support, and menu categories. Write component docs in .mdx files (e.g., a Button page) and run npm run docz:dev to preview locally.

Customising docz theme : Override the default theme by creating theme/gatsby-theme-docz/components/Header/index.js and styles.js . This allows adding a custom logo or adjusting layout without modifying the library source.

Deploying docs : Host the generated docsite on GitHub Pages or Netlify. For Netlify, connect the GitHub repository, set the publish directory to docsite , and optionally configure a custom domain.

On‑demand loading : Two approaches are described. The first uses babel-plugin-import (or babel-plugin-impor ) to rewrite imports to reactui/dist/components/Button and automatically include the component’s style. The second leverages Webpack tree‑shaking by setting "sideEffects": false in package.json and excluding SCSS files via "sideEffects": ["*.scss"] , allowing consumers to import components without extra Babel configuration.

Style on‑demand loading : Each component’s index.tsx imports its own SCSS ( import './button.scss' ). A custom build step uses node‑sass ’s sass.render to compile each SCSS file to a corresponding .scss (or .css ) file placed next to the component in dist/components , enabling per‑component style imports.

The article concludes that while the tooling chain (create‑react‑app, docz, Netlify) accelerates library creation, fine‑tuning the build and documentation pipelines still requires careful experimentation, and invites readers to share their own improvements.