Component Library Documentation

Project Overview

This is a React component library built with TypeScript, Vite, and Tailwind CSS. It provides reusable UI components for React applications.

Project Structure

boilerplate-component-library/
├── .gitlab/
│   └── merge_request_templates/
│       └── mytemplate.md
├── lib/
│   ├── components/
│   │   ├── atoms/
│   │   ├── molecules/
│   │   └── organism/
│   ├── main.tsx
│   └── index.css
├── .eslintrc.json
├── .gitignore
├── jest.config.ts
├── jest.setup.ts
├── vite.config.ts
├── tsconfig.json
└── README.md

Setup and Installation

1. Clone the repository
2. Install dependencies: npm install

Local Testing

To test the library locally without publishing:

1. After you made changes to your package, build your project.

2. Run "npm link" in the package repo. Then run "npm link <package-name>" in the project that wants to use the package. This will register the package in the node_modules folder.

Publishing

To publish the library to NPM:

1. Update the package name and version in package.json. Ensure your package name is unique.

2. Build your project: npm run build

3. Run "npm publish" to publish or update your package

Storybook

For component development and documentation:

npm run storybook

Testing

Run tests:

npm run test

Update snapshots:

jest -u

For more detailed information on writing unit tests in a Next.js project using Jest, including setup instructions, best practices, and advanced techniques, please refer to our comprehensive guide:

Writing Unit Tests in a Next.js Project Using Jest

This guide covers topics such as:

• Setting up Jest in a Next.js project
• Writing basic unit tests for React components
• UI testing and simulating user interactions
• Understanding the difference between unit and integration tests
• Mocking data and external dependencies
• Generating and interpreting test coverage reports
• Best practices for writing effective unit tests

Components

The library follows the atomic design methodology for organizing components. This approach helps create a scalable and maintainable component structure.

Atomic Design Best Practices

For detailed information on implementing atomic design in our component library, please refer to our comprehensive guide:

Atomic Design Component Creation

1. Atoms:

   • Create the smallest, most basic building blocks (e.g., buttons, inputs, labels).
   • Keep atoms as simple and versatile as possible.
   • Avoid business logic in atoms.

2. Molecules:

   • Combine multiple atoms to form more complex UI elements (e.g., search bars, form fields with labels).
   • Focus on a single responsibility or functionality.
   • Can contain some simple business logic.

3. Organisms:

   • Compose of multiple molecules and/or atoms to create distinct sections of the interface (e.g., headers, forms, product cards).
   • May include more complex business logic.
   • Should be context-independent and reusable across different pages.

Best Practices for Component Development

• Maintain clear separation between atoms, molecules, and organisms.
• Design components to be as reusable and flexible as possible.
• Use props to make components customizable and adaptable to different contexts.
• Keep components focused on a single responsibility (Single Responsibility Principle).
• Document each component thoroughly, including its purpose, props, and usage examples.
• Create Storybook stories for each component to showcase its variations and usage.
• Write comprehensive unit tests for all components.

By following these atomic design principles and best practices, you can create a well-structured, maintainable, and scalable component library.

Styling

Tailwind CSS is used for styling components. Custom styles can be added in lib/index.css.

Code Standardization

To ensure consistent code quality across the project, we follow a set of code standardization practices. These include:

• Using ESLint for code linting
• Applying Prettier for code formatting
• Following specific rules for import order, component definitions, and naming conventions

For a comprehensive guide on our code standardization practices, including detailed ESLint and Prettier configurations, please refer to our Next.js Code Standardization Guide.

This guide covers:

• ESLint and Prettier setup
• Detailed explanation of linting rules
• Code examples for correct and incorrect practices
• Editor configuration tips

Adhering to these standards helps maintain code consistency, improves readability, and reduces potential errors across the project.

Best Practices

1. Follow the component structure (atoms, molecules, organisms).
2. Write unit tests for all components.
3. Use Storybook for component development and documentation.
4. Follow ESLint and Prettier rules for consistent code style.
5. Update snapshots when necessary using jest -u.

Contributing

Use the merge request template in .gitlab/merge_request_templates/mytemplate.md for consistent code reviews.

This documentation focuses specifically on your component library, excluding any application-specific components or configurations. It covers the essential aspects of building, testing, and publishing your library, as well as best practices for development and contribution.