denisfloyd / my-turbo-components

Tailwindcss Design System built with Turborepo + changeset

Design System built with tailwindcss

📌 Table of Contents

• Technologies
• How to Run
• Run Tests
• Found a bug? Missing a specific feature?
• Contributing
• Project definition
• License

💻 Technologies

This guide explains how to use a React design system starter powered by:

• 🏎 Turborepo — High-performance build system for Monorepos
• 🚀 React — JavaScript library for user interfaces
• 🎨 TailwindCss - Utility-first CSS framework for rapidly building modern websites
• 🛠 Tsup — TypeScript bundler powered by esbuild
• 📖 Storybook — UI component environment powered by Vite

As well as a few others tools preconfigured:

• Tailwind-Variants The power of Tailwind combined with a first-class variant API.
• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting
• Changesets for managing versioning and changelogs
• GitHub Actions for fully automated package publishing

👷 How to run

# Clone the project on your computer via Download (option Code -> Download ZIP)
    - If you want to do it with Git, make sure you have Git installed,
      follow the link https://git-scm.com/
    - then run the command in terminal:
        $ git clone https://github.com/denisfloyd/my-turbo-components.git

# In the terminal or prompt(cmd), access the project root;
   $ cd my-turbo-components

obs. Make sure you have Node installed in your computer. I highly recommend to use pnpm instead npm or yarn to download the dependencies.

Useful Commands

• pnpm build - Build all packages, including the Storybook site
• pnpm dev - Run all packages locally and preview with Storybook
• pnpm prettier - Prettier all packages
• pnpm lint - Lint all packages
• pnpm test - Run package tests (you can also run separately on each package)
• npx changeset - Generate a changeset
• pnpm clean - Clean up all node_modules and dist folders (runs each package's clean script)

🧪 Run Tests

# Install dependencies if you didn't
# Run tests
$ pnpm run test

# Run test coverage
$ pnpm run test:coverage

🐛 Issues

Feel free to file a new issue with a respective title and description on the the My Turbo Components repository. If you already found a solution to your problem, i would love to review your pull request!

🎉 Contributing

There are many forms to contribute with the project, first of all you can give this github repo a Star.

If you want do help with the code follow the steps bellow

# Fork using GitHub official command line
# If you don't have the GitHub CLI, use the web site to do that.
$ gh repo fork denisfloyd/my-turbo-components
# Clone your fork
$ git clone {your-fork-url}
$ cd my-turbo-components

# Create a branch with your feature
$ git checkout -b {branch-name}

# Make the commit with your changes
$ git commit -m 'Feat: {feature-name}'

# Send the code to your remote branch
$ git push origin {branch-name}

📖 Project Definition

Turborepo

Turborepo is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching.

Using Turborepo simplifies managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. Learn more about how monorepos improve your development workflow.

Apps & Packages

This Turborepo includes the following packages and applications:

• apps/docs: Component documentation site with Storybook
• packages/df-<component-name>: Component package
• packages/df-tsconfig: Shared tsconfig.jsons used throughout the Turborepo
• packages/eslint-config-df: ESLint preset
• packages/jest-config-df: Jest preset

Each package and app is 100% TypeScript. Workspaces enables us to "hoist" dependencies that are shared between packages to the root package.json. This means smaller node_modules folders and a better local dev experience. To install a dependency for the entire monorepo, use the -w workspaces flag with pnpm add.

Compilation

To make the packages libraries code work across all browsers, we need to compile the raw TypeScript and React code to plain JavaScript. We can accomplish this with tsup, which uses esbuild to greatly improve performance.

Running pnpm build from the root of the Turborepo will run the build command defined in each package's package.json file. We define for each package a tsupconfig file. Turborepo runs each build in parallel and caches & hashes the output to speed up future builds.

E.g df-button package, the build command (tsup) use this setup:

export default defineConfig((options: Options) => ({
  treeshake: true,
  splitting: true,
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  minify: true,
  clean: true,
  external: ['react'],
  ...options,
}));

tsup compiles src/index.tsx/ts, which exports all of the components in the design system, into both ES Modules and CommonJS formats as well as their TypeScript types. The package.json for any package, e.g df-button then instructs the consumer to select the correct format:

{
  "name": "df-button",
  "version": "0.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "sideEffects": [
    "**/*.css"
  ],
  "license": "MIT",
  "exports": {
    ".": "./dist",
    "./styles.css": "./dist/index.css"
  },
}

Run pnpm build to confirm compilation is working correctly. You should see a folder e.g. packages/df-button/dist which contains the compiled output.

  apps
    ...
  packages
  └── df-button
    └── dist
        ├── index.d.ts  <-- Types
        ├── index.js    <-- CommonJS version
        └── index.mjs   <-- ES Modules version

Components

Each file inside of package is a component inside our design system. For example:

  apps
    ...
  packages
    └── df-button
    └── df-input
  ...

Versioning & Publishing Packages

This example uses Changesets to manage versions, create changelogs, and publish to npm. It's configured so you can start publishing packages immediately.

Generating the Changelog

To generate your changelog, run npx changeset in your local branch:

1. Which packages would you like to include? – This shows which packages and changed and which have remained the same. By default, no packages are included. Press space to select the packages you want to include in the changeset.
2. Which packages should have a major bump? – Press space to select the packages you want to bump versions for.
3. If doing the first major version, confirm you want to release.
4. Write a summary for the changes.
5. Confirm the changeset looks as expected.
6. A new Markdown file will be created in the changeset folder with the summary and a list of the packages included.

Releasing

When you raise a new pull request to GitHub with your changelogs, the GitHub Action will run the release workflow. Then after your changes go to production (main), changeset will create a "Release's Pull Request" automatically.

📕 License

Released in 2023 📕 License

Made with love by Denis Ladeira 🚀. This project is under the MIT license.