JS Package Template

A comprehensive template for creating publishable JavaScript/TypeScript packages with built-in testing, Next.js integration, and automated publishing workflow.

Global CLI Installation

Install the CLI globally to create new packages anywhere:

# Clone and build this template first
git clone <your-repo-url> js-package-template
cd js-package-template
pnpm install
pnpm build

# Install globally
npm link
# or
pnpm link --global

# Now you can use it anywhere
create-js-package create my-awesome-package
cd my-awesome-package
pnpm install

CLI Commands

• create-js-package create <name> - Create a new package in a directory
• create-js-package create <name> --dir <path> - Create in specific directory
• create-js-package init - Initialize current directory as a package

Features

• TypeScript Support: Full TypeScript support with separate builds for browser and server environments
• Automated Publishing: Simple pnpm run pub --name <package-name> command for publishing to npm
• Testing Setup:
  • Unit tests with Vitest
  • E2E tests with Playwright
  • Dynamic Next.js app creation for testing
• Next.js Integration: Optimized for use in Next.js applications
• Dual Environment Support: Separate exports for browser and server code
• Test Utilities: createNext utility for spinning up Next.js apps dynamically in tests
• Visualization Dashboard: Built-in app to visualize tests and package information

Quick Start

1. Install dependencies:

pnpm install

2. Build the package:

pnpm build

3. Run tests:

pnpm test        # Run all tests
pnpm test:unit   # Run unit tests only
pnpm test:e2e    # Run e2e tests only

4. Publish to npm:

pnpm run pub --name my-package-name

Project Structure

├── src/
│   ├── browser/        # Browser-specific code
│   ├── server/         # Server-specific code
│   └── test-utils/     # Testing utilities
├── tests/
│   ├── unit/          # Unit tests
│   └── e2e/           # E2E tests
├── examples/
│   ├── next-app/      # Example Next.js app
│   └── vite-app/      # Example Vite app
└── visualization-app/  # Test visualization dashboard

Using the Package

Browser Code

import { browserFunction, createBrowserLogger } from 'my-package/browser'

const logger = createBrowserLogger()
logger.log('Hello from browser!')

Server Code

import { serverFunction, createServerLogger } from 'my-package/server'

const logger = createServerLogger()
logger.log('Hello from server!')

Test Utilities

import { createNext } from 'my-package/test-utils'

const app = await createNext({
  files: {
    'app/page.tsx': `export default function Page() { return <h1>Test</h1> }`
  }
})
// App is now running at app.url
await app.cleanup() // Clean up when done

Visualization Dashboard

Start the visualization app to see package info and run tests:

cd visualization-app
pnpm install
pnpm dev

Visit http://localhost:4000 to see:

• Package information
• Exported functions
• Test runner with live results

Scripts

• pnpm dev - Start development mode with watch
• pnpm build - Build the package
• pnpm test - Run all tests
• pnpm typecheck - Run TypeScript type checking
• pnpm lint - Run ESLint
• pnpm format - Format code with Prettier
• pnpm pub --name <name> - Publish package to npm

License

MIT