@metadiv-studio/template

A starter template for creating UI component packages with TypeScript, React, and modern build tools. This template provides everything you need to build, test, and publish React components as npm packages.

🚀 Quick Start

1. Clone and customize this template for your component library
2. Develop your components in the src/ folder
3. UI Test your components using the built-in testing environment:

   npm run dev

4. Prepublish Test your package:

   npm run build

5. Publish your package to npm:

   npm publish

📁 Project Structure

template/
├── src/                    # Your component source code
│   ├── components/         # Component implementations
│   └── index.ts           # Main exports (what gets published)
├── pages/                  # Component testing environment
│   ├── _app.tsx           # Next.js app wrapper
│   ├── index.tsx          # Testing page
│   └── globals.css        # Global styles
└── dist/                   # Generated build output (published to npm)

🛠️ Development Workflow

1. Component Development (src/ folder)

Write your React components in the src/ folder. This is where your actual component library code lives.

2. Export Your Components (src/index.ts)

The src/index.ts file is crucial - it defines what gets exported from your package. Only components exported here will be available to consumers.

// src/index.ts
export { Button } from './components/Button';
export type { ButtonProps } from './components/Button';

// Export default component if needed
export { default as Badge } from './components/Badge';

3. Testing Your Components (pages/ folder)

The pages/ folder contains a Next.js testing environment. Use npm run dev to start the development server and test your components in a real browser environment.

npm run dev

This will start a local development server where you can:

• See your components rendered
• Test different props and states
• Debug styling and interactions
• Ensure components work as expected

4. Building for Production

Generate the dist/ folder with compiled JavaScript and TypeScript declarations:

npm run build

This command:

• Cleans the previous build
• Compiles TypeScript to JavaScript
• Generates type declaration files (.d.ts)
• Outputs everything to the dist/ folder

5. Publishing Your Package

Before publishing, change the package name in package.json from @metadiv-studio/template to your own package name:

{
  "name": "@metadiv-studio/your-package-name",  // Change this to your actual package name
  "version": "1.0.1"           // Increment this every time
}

Then publish:

npm login
npm publish

Important: Only the dist/ folder gets published to npm, not your source code.

Note: The publish command will automatically rebuild the dist file to ensure the package contains your latest component updates.

📦 Package Configuration

Tailwind CSS Configuration

Important: For consumers to use your package's Tailwind CSS styles, they must add the following path to their tailwind.config.js or tailwind.config.ts file:

// tailwind.config.js
module.exports = {
  content: [
    // ... other content paths
    "./node_modules/@metadiv-studio/**/*.{js,ts,jsx,tsx}",
  ],
  // ... rest of config
}

This ensures that Tailwind can scan your package's components and include the necessary CSS classes in the final build.

Entry Points

Your package is configured with multiple entry points for maximum compatibility:

{
  "main": "./dist/index.js",        // CommonJS entry
  "module": "./dist/index.js",      // ES Module entry
  "types": "./dist/index.d.ts",     // TypeScript declarations
  "exports": {
    ".": {
      "import": "./dist/index.js",  // ES Module import
      "types": "./dist/index.d.ts"  // TypeScript types
    }
  }
}

Scripts

{
  "scripts": {
        "build": "rimraf dist && rimraf tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json && node scripts/fix-imports.mjs",
    "dev": "next dev",
    "clean": "rimraf dist && rimraf tsconfig.build.tsbuildinfo",
    "prepublishOnly": "npm run build"
  }
}

🎯 Design Intent & Configuration

1. TypeScript Build Configuration

Why this setup: The tsconfig.build.json file is specifically configured to preserve TypeScript settings for testing with pages while successfully exporting files to the dist folder with the right format. It extends the main tsconfig.json and sets noEmit: false to ensure proper compilation output.

Don't change: The build script automatically removes tsconfig.build.tsbuildinfo to ensure clean builds. Avoid modifying these TypeScript configurations as they are carefully designed to handle both development testing and production builds.

2. CSS Modules Limitation

Why this limitation: CSS modules are intentionally not supported in this template to maintain simplicity and avoid complex build configurations.

Don't change: This template is designed to work with Tailwind CSS (already configured), styled-components, or emotion. Avoid trying to add CSS modules support as it would require significant build configuration changes and could introduce compatibility issues.

3. ESM Import Handling

Why this automation: ESM packages require explicit .js file extensions, but TypeScript doesn't add them automatically. This is automatically handled by the scripts/fix-imports.mjs script during the build process.

Don't change: The script automatically adds .js extensions to all relative imports in your compiled JavaScript files. Avoid modifying this script as it ensures ESM compatibility without requiring manual import path management.

Styling Solutions

• Tailwind CSS: Already configured
• CSS Modules: Requires additional build steps (see CSS Modules section)
• Styled Components: Add as dependency
• Emotion: Add as dependency

📚 Best Practices

1. Always export from src/index.ts - This is your public API
2. Test components thoroughly using the built-in testing environment
3. Update version before publishing - Use semantic versioning
4. Keep dependencies minimal - Use peerDependencies for React/React-DOM
5. Generate clean builds - Always run npm run build before testing
6. ESM import issues are automatically fixed by the build script

🚀 Publishing Checklist

Before publishing, ensure:

• [ ] Package name is changed in package.json from @metadiv-studio/template to your actual package name
• [ ] Components are properly exported in src/index.ts
• [ ] npm run build completes successfully
• [ ] dist/ folder contains all necessary files
• [ ] Version is updated in package.json
• [ ] Components work correctly in testing environment
• [ ] Build script automatically fixes ESM import issues

🤝 Contributing

This template is designed to be a starting point. Feel free to:

• Modify the build configuration
• Add additional tooling
• Customize the testing environment
• Extend the TypeScript configuration

Happy component building! 🎉