First React Component Test

Panduan lengkap membuat library React dari nol hingga publish ke npm.

📋 Daftar Isi

• Pendahuluan
• Prasyarat
• 1. Setup Proyek Awal
• 2. Membuat Struktur Folder
• 3. Konfigurasi Vite
• 4. Membuat Komponen React
• 5. Setup Storybook
• 6. Build Library
• 7. Testing (Opsional)
• 8. Publish ke NPM
• Troubleshooting

📖 Pendahuluan

Library ini adalah template untuk membuat React Component Library yang dapat dipublikasikan di npm. Library ini dirancang untuk:

• ✅ Mendukung CommonJS (UMD) dan ES Modules
• ✅ Menggunakan Storybook untuk dokumentasi komponen
• ✅ Optimasi bundle dengan Vite
• ✅ Support React 18+ dan React 19+
• ✅ TypeScript & JavaScript support
• ✅ Testing dengan Vitest

🔧 Prasyarat

Sebelum memulai, pastikan Anda sudah menginstall:

• Node.js (v18+): Download di nodejs.org
• npm (v9+) atau yarn (v3+)
• Git: Untuk version control
• npm account: Untuk publish ke npm (https://www.npmjs.com/)

Verifikasi instalasi:

node --version
npm --version
git --version

1. Setup Proyek Awal

1.1 Buat Folder Proyek

mkdir first-react-component-test
cd first-react-component-test

1.2 Inisialisasi Git

git init
git config user.name "Nama Anda"
git config user.email "[email protected]"

1.3 Inisialisasi npm

npm init -y

Ini akan membuat package.json dengan konfigurasi default.

1.4 Update package.json

Edit package.json dan sesuaikan dengan informasi library Anda:

{
  "name": "first-react-component-test",
  "version": "1.0.0",
  "description": "Komponen React kustom pertamaku",
  "type": "module",
  "main": "./dist/index.umd.js",
  "module": "./dist/index.es.js",
  "exports": {
    ".": {
      "import": "./dist/index.es.js",
      "require": "./dist/index.umd.js"
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  },
  "keywords": [
    "react",
    "component"
  ],
  "author": "Nama Anda",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/first-react-component-test"
  },
  "bugs": {
    "url": "https://github.com/username/first-react-component-test/issues"
  },
  "homepage": "https://github.com/username/first-react-component-test#readme"
}

Penjelasan field penting:

• name: Nama package di npm (harus unik)
• main: Entry point untuk CommonJS
• module: Entry point untuk ES Modules
• exports: Mendefinisikan multiple entry points
• files: File yang akan dipublikasikan ke npm
• peerDependencies: Dependency yang harus diinstall oleh user

2. Membuat Struktur Folder

Buat struktur folder proyek:

mkdir -p src/stories
touch src/index.js
touch .gitignore
touch .npmrc

Struktur folder akhir:

first-react-component-test/
├── node_modules/
├── src/
│   ├── components/
│   │   ├── ChatTrigger.tsx
│   │   ├── ChatWindow.tsx
│   │   └── MyComponent.jsx
│   ├── stories/
│   │   ├── ChatTrigger.stories.jsx
│   │   ├── ChatWindow.stories.jsx
│   │   └── MyComponent.stories.jsx
│   └── index.js
├── dist/ (generated saat build)
├── .gitignore
├── .npmrc
├── vite.config.js
├── package.json
└── README.md

2.1 Buat .gitignore

cat > .gitignore << 'EOF'
# Dependencies
node_modules/
package-lock.json
yarn.lock
pnpm-lock.yaml

# Build output
dist/
build/

# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# IDE
.vscode/
.idea/
*.swp
*.swo
.DS_Store

# Storybook
storybook-static/

# Environment variables
.env
.env.local
EOF

2.2 Buat .npmrc

File ini mengonfigurasi npm publishing:

cat > .npmrc << 'EOF'
# Publish public packages
access=public

# Optional: set registry (gunakan jika menggunakan private registry)
# registry=https://registry.npmjs.org/
EOF

3. Konfigurasi Vite

3.1 Install Dependencies

npm install --save-dev vite @vitejs/plugin-react
npm install --save-dev @storybook/react-vite storybook

3.2 Buat vite.config.js

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      // Entry point ke index.js di folder src
      entry: resolve(__dirname, 'src/index.js'),
      name: 'FirstReactComponentTest',
      // Format output: ES module dan UMD
      formats: ['es', 'umd'],
      fileName: (format) => `index.${format}.js`,
    },
    rollupOptions: {
      // Jangan masukkan react ke dalam bundle
      external: ['react', 'react-dom', 'react/jsx-runtime'],
      output: {
        // Konfigurasi global variables untuk UMD
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
          'react/jsx-runtime': 'jsxRuntime'
        }
      }
    }
  }
});

4. Membuat Komponen React

4.1 Buat File Komponen

Contoh src/components/MyComponent.jsx:

import React from 'react';
import PropTypes from 'prop-types';

export const MyComponent = ({ title, description, onClick }) => {
  return (
    <div style={{
      padding: '20px',
      border: '1px solid #ccc',
      borderRadius: '8px',
      backgroundColor: '#f9f9f9'
    }}>
      <h2>{title}</h2>
      <p>{description}</p>
      <button onClick={onClick}>Click Me</button>
    </div>
  );
};

MyComponent.propTypes = {
  title: PropTypes.string.isRequired,
  description: PropTypes.string,
  onClick: PropTypes.func
};

MyComponent.defaultProps = {
  description: 'Deskripsi komponen',
  onClick: () => console.log('Button clicked')
};

4.2 Buat File TypeScript (Opsional)

Contoh src/components/ChatTrigger.tsx:

import React, { FC, ReactNode } from 'react';

interface ChatTriggerProps {
  children?: ReactNode;
  onOpen?: () => void;
  variant?: 'primary' | 'secondary';
}

export const ChatTrigger: FC<ChatTriggerProps> = ({
  children = 'Open Chat',
  onOpen,
  variant = 'primary'
}) => {
  return (
    <button
      onClick={onOpen}
      style={{
        padding: '10px 20px',
        backgroundColor: variant === 'primary' ? '#007bff' : '#6c757d',
        color: '#fff',
        border: 'none',
        borderRadius: '4px',
        cursor: 'pointer'
      }}
    >
      {children}
    </button>
  );
};

4.3 Buat File Index (Entry Point)

src/index.js:

// Export semua komponen
export { MyComponent } from './components/MyComponent.jsx';
export { ChatTrigger } from './components/ChatTrigger.tsx';
export { ChatWindow } from './components/ChatWindow.tsx';

// Atau dengan named exports
// export * from './components/MyComponent.jsx';
// export * from './components/ChatTrigger.tsx';
// export * from './components/ChatWindow.tsx';

5. Setup Storybook

Storybook membantu Anda mendokumentasikan dan menguji komponen secara visual.

5.1 Install Storybook

npx storybook@latest init --type react

Atau manual:

npm install --save-dev storybook @storybook/react @storybook/react-vite

5.2 Buat .storybook/main.js

export default {
  stories: ['../src/**/*.stories.{js,jsx,ts,tsx}'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-onboarding'
  ],
  framework: '@storybook/react-vite',
  core: {
    builder: '@storybook/builder-vite'
  }
};

5.3 Buat File Story

src/components/MyComponent.stories.jsx:

import { MyComponent } from './MyComponent';

export default {
  title: 'Components/MyComponent',
  component: MyComponent,
  tags: ['autodocs'],
};

export const Primary = {
  args: {
    title: 'Hello Component',
    description: 'Ini adalah contoh komponen'
  }
};

export const Secondary = {
  args: {
    title: 'Secondary Variant',
    description: 'Variant kedua dari komponen',
    onClick: () => alert('Tombol diklik!')
  }
};

5.4 Jalankan Storybook

npm run storybook

Storybook akan berjalan di http://localhost:6006

6. Build Library

6.1 Build untuk NPM

npm run build

Ini akan menghasilkan folder dist/ dengan:

• dist/index.es.js - ES Module format
• dist/index.umd.js - UMD format (untuk browser dan Node.js)

6.2 Verifikasi Build

ls -la dist/

Seharusnya Anda melihat dua file yang dihasilkan.

6.3 Test Build Lokal (Opsional)

Untuk test apakah package bisa diinstall:

# Di folder proyek lain
npm install /path/to/first-react-component-test

7. Testing (Opsional)

7.1 Install Vitest

npm install --save-dev vitest @testing-library/react @testing-library/jest-dom

7.2 Setup vitest.config.js

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/test/setup.js'
  }
});

7.3 Buat Test File

src/components/MyComponent.test.jsx:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('renders with title', () => {
    render(<MyComponent title="Test Title" />);
    expect(screen.getByText('Test Title')).toBeInTheDocument();
  });

  it('displays description', () => {
    render(<MyComponent title="Test" description="Test Description" />);
    expect(screen.getByText('Test Description')).toBeInTheDocument();
  });
});

7.4 Update package.json

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui"
  }
}

7.5 Jalankan Test

npm run test
npm run test:ui

8. Publish ke NPM

8.1 Persiapan Pre-Publish

# 1. Pastikan build sudah terbuat
npm run build

# 2. Verifikasi package.json
cat package.json | grep -E '"name"|"version"|"main"|"module"'

# 3. Commit semua perubahan
git add .
git commit -m "Initial commit"

# 4. Create tag version
git tag v1.0.0

8.2 Login ke NPM

npm login

Masukkan:

• Username npm Anda
• Password
• Email
• OTP (One-Time Password) jika enabled

Verifikasi login:

npm whoami

8.3 Test Publish (Opsional)

Sebelum publish ke npm public, Anda bisa test dengan npm dry-run:

npm publish --dry-run

Ini akan menampilkan file apa saja yang akan dipublikasikan tanpa benar-benar publish.

8.4 Publish ke NPM

npm publish

Output yang diharapkan:

npm notice
npm notice 📦  [email protected]
npm notice === Tarball Contents ===
npm notice 258B dist/index.es.js
npm notice 312B dist/index.umd.js
npm notice 456B package.json
npm notice === Tarball Details ===
npm notice name:          first-react-component-test
npm notice version:       1.0.0
npm notice ...

8.5 Verifikasi Publish

# Cek di npm registry
npm view first-react-component-test

# Atau kunjungi: https://www.npmjs.com/package/first-react-component-test

9. Update dan Re-publish

9.1 Semantic Versioning

Gunakan format MAJOR.MINOR.PATCH:

1.2.3
│ │ └─ PATCH (bug fixes)
│ └─── MINOR (new features, backward compatible)
└───── MAJOR (breaking changes)

9.2 Update Version

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

Ini akan:

• Update package.json
• Create git tag otomatis
• Commit changes

9.3 Re-publish

npm publish

🚀 Cara Menggunakan Library

Setelah publish, user bisa install library Anda:

npm install first-react-component-test

Import dan Gunakan

Di React App:

import React from 'react';
import { MyComponent, ChatTrigger } from 'first-react-component-test';

function App() {
  return (
    <div>
      <MyComponent title="Hello" description="Welcome" />
      <ChatTrigger onOpen={() => console.log('opened')} />
    </div>
  );
}

export default App;

🐛 Troubleshooting

Masalah: "Cannot find module 'react'"

Penyebab: React tidak diinstall di project yang menggunakan library.

Solusi:

npm install react react-dom

Masalah: "Module is not defined"

Penyebab: Konfigurasi Vite tidak benar.

Solusi: Pastikan vite.config.js memiliki:

plugins: [react()],

Masalah: Build tidak menghasilkan file di dist

Penyebab: Entry point tidak benar atau index.js kosong.

Solusi: Verifikasi src/index.js export komponen dengan benar:

export { MyComponent } from './components/MyComponent.jsx';

Masalah: Publish gagal "Package name already exists"

Penyebab: Nama package sudah terdaftar di npm.

Solusi: Gunakan nama unik dengan scope:

{
  "name": "@username/first-react-component-test"
}

Masalah: Storybook tidak bisa jalankan komponen

Penyebab: Dependencies TypeScript tidak terinstall.

Solusi:

npm install --save-dev typescript
npm install --save-dev @types/react @types/react-dom

📚 Resources Tambahan

• Vite Documentation
• Storybook Documentation
• NPM Publishing Guide
• React Documentation
• Semantic Versioning

📝 Checklist Pre-Publish

Sebelum publish, pastikan:

• [ ] package.json sudah dikonfigurasi dengan benar
• [ ] name unik dan belum terdaftar di npm
• [ ] version sudah diupdate sesuai semantic versioning
• [ ] main dan module menunjuk ke file yang benar
• [ ] files include folder dist
• [ ] Build berhasil tanpa error: npm run build
• [ ] Semua file dikompilasi di folder dist
• [ ] Git sudah diinit dan commit pertama sudah dibuat
• [ ] .npmrc sudah dibuat
• [ ] Sudah login ke npm: npm whoami
• [ ] Storybook running dengan baik
• [ ] README.md lengkap dengan dokumentasi

📄 License

MIT License - Gratis untuk digunakan secara komersial dan pribadi.

Happy Publishing! 🎉