npm package: @repl-utils/test
Description: A template for creating publishable JS packages with TypeScript, testing, and Next.js integration
Latest version: 0.1.2

# 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:

```bash
# 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:
```bash
pnpm install
```

2. Build the package:
```bash
pnpm build
```

3. Run tests:
```bash
pnpm test        # Run all tests
pnpm test:unit   # Run unit tests only
pnpm test:e2e    # Run e2e tests only
```

4. Publish to npm:
```bash
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
```typescript
import { browserFunction, createBrowserLogger } from 'my-package/browser'

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

### Server Code
```typescript
import { serverFunction, createServerLogger } from 'my-package/server'

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

### Test Utilities
```typescript
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:

```bash
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