UI SDK Development Structure

This repository provides a well-organized, scalable, and reusable structure for developing a UI SDK using React. The SDK is designed to be modular, enforce coding standards, and include testing, linting, and formatting, along with interactive documentation through Storybook.

Directory Structure

.
├── .husky/                      # Git hooks for linting, formatting, and testing
├── babel.config.js              # Babel configuration for transpiling modern JS
├── dist/                        # Generated output files for publishing
├── eslint.config.mjs            # ESLint configuration for code quality
├── jest.config.js               # Jest configuration for testing
├── package.json                 # Node.js project metadata and scripts
├── rollup.config.js             # Rollup bundler configuration
├── src/                         # Source code
│   ├── components/              # All React components
│   │   ├── Accordion/           # Accordion component
│   │   │   ├── Accordion.jsx    # Accordion component logic
│   │   │   ├── Accordion.css    # Styles for Accordion
│   │   │   ├── Accordion.test.jsx  # Unit tests for Accordion
│   │   │   └── Accordion.stories.jsx # Storybook stories for Accordion
│   │   └── Grid/                # Grid component
│   │       ├── Grid.jsx         # Grid component logic
│   │       ├── Grid.css         # Styles for Grid
│   │       ├── Grid.test.jsx    # Unit tests for Grid
│   │       └── Grid.stories.jsx # Storybook stories for Grid
│   ├── index.js                 # Entry point for exporting components
│   └── styles/                  # Global styles
│       └── global.css           # Shared styles like colors, fonts, spacing
├── tests/                       # Shared mocks and helpers for testing
│   └── __mocks__/               # Jest mocks
│       └── styleMock.js         # Mock styles for Jest

Key Features

• Modular Components: Each component has its logic, styles, tests, and stories in its directory.
• Global and Scoped Styles: global.css defines shared variables (e.g., colors, fonts, spacing), while component-specific styles are scoped to individual components.
• Interactive Documentation: Storybook enables visual testing and documentation of components.
• Automated Quality Control: Husky enforces linting, formatting, and testing before commits.
• Ready for Distribution: Rollup bundles components into a distributable format.

Setup Guide

1. Clone the repository or create a new project.
2. Install dependencies:

   npm install

3. Initialize Husky for Git hooks:

   npx husky install

4. Start Storybook:

   npm run storybook

5. Run tests:

   npm run test

6. Build the package for distribution:

   npm run build

Adding a New Component

1. Create a Component Folder:
   Inside src/components/, create a folder named after your component (e.g., Button).

2. Add Component Files:

   • Button.jsx: Component logic.
   • Button.css: Component-specific styles.
   • Button.test.jsx: Unit tests.
   • Button.stories.jsx: Storybook stories.

   Example file structure for the Button component:

   src/components/Button/
   ├── Button.jsx
   ├── Button.css
   ├── Button.test.jsx
   └── Button.stories.jsx

3. Export the Component: Add an export in src/index.js:

   export { default as Button } from "./components/Button/Button.jsx";

4. Test and Document:

   • Run tests: npm run test
   • Preview in Storybook: npm run storybook

Detailed Explanation of Files

1. src/index.js

• Serves as the entry point for exporting all components in the SDK.
• Ensures components can be imported like:

  import { Accordion, Grid } from "@your-package/ui-sdk";

2. Component-Specific Files

• Component.jsx: Contains the component’s logic and behavior.
• Component.css: Defines styles specific to the component.
• Component.test.jsx: Jest tests to ensure the component behaves as expected.
• Component.stories.jsx: Storybook stories for visual testing and documentation.

3. Global Styles

• styles/global.css:
  • Defines global variables for colors, fonts, and spacing.
  • Example:

    :root {
      --primary-color: #007bff;
      --spacing: 1rem;
      --font-family: Arial, sans-serif;
    }

4. Rollup Configuration

• rollup.config.js: Configures bundling for the SDK.
  • Outputs both CommonJS (cjs) and ES Module (esm) formats.
  • Excludes external dependencies like React.

5. Husky Git Hooks

• Ensures code quality by running linting, formatting, and testing before commits.

6. Testing Configuration

• jest.config.js: Configures Jest for testing.
• __mocks__/styleMock.js: Mocks CSS imports during testing.

Scripts in package.json

Core Scripts

• npm start: Launches Storybook for interactive documentation.
• npm run build: Bundles the SDK into the dist/ folder for distribution.
• npm run test: Runs all Jest tests.
• npm run lint: Lints the codebase with ESLint.
• npm run storybook: Starts Storybook.

Husky Automation

• Pre-commit hook: Runs lint-staged to lint, format, and test staged files.

Best Practices

1. Follow Component Structure:
   • Keep component logic, styles, tests, and stories modular.
2. Write Tests:
   • Ensure comprehensive test coverage for all components.
3. Document Components:
   • Use Storybook to create interactive documentation.
4. Enforce Coding Standards:
   • Use ESLint and Prettier for consistent formatting and quality.
5. Leverage Global Styles:
   • Define reusable variables in global.css for consistency.

Why Use This Structure?

• Scalability: Easily add new components without affecting existing ones.
• Maintainability: Separation of concerns improves debugging and collaboration.
• Consistency: Shared global styles and strict linting ensure a cohesive design.
• Reusable SDK: Bundle and publish components for use in multiple projects.

This structure will help developers to build robust, scalable, and maintainable UI SDKs with minimal overhead.