npm package: @incidental/project-templates
Description: Claude Code template library for JavaScript projects with framework auto-detection
Author: Incidental
Latest version: 1.0.0

# @incidental/project-templates

> Claude Code template library for JavaScript projects with framework auto-detection

A comprehensive npm package that provides pre-built Claude Code customizations (commands, agents, skills, and steering documents) that can be easily installed into any JavaScript project via npx commands.

[![npm version](https://img.shields.io/npm/v/@incidental/project-templates.svg)](https://www.npmjs.com/package/@incidental/project-templates)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🚀 **Framework Auto-Detection** - Automatically detects Next.js, React.js, or vanilla JavaScript
- 📦 **Multi-Command CLI** - Install templates individually or all at once
- 🎯 **Framework-Specific Templates** - Optimized commands and agents for your framework
- 🛠️ **Production-Ready** - Battle-tested templates following best practices
- 📚 **Comprehensive Library** - Commands, agents, skills, and steering documents
- ⚡ **Zero Config** - Works out of the box with sensible defaults

## What's Included

### Commands
- **Next.js**: Create pages, API routes, optimize images
- **React**: Create components, add state management, setup routing
- **Vanilla JS**: Create modules, bundle optimization
- **Shared**: Run tests, generate docs, git workflows

### Agents
- **Next.js Expert**: App Router, Server Components, optimization
- **React Expert**: Components, hooks, performance
- **Test Runner**: Automated testing and fixing
- **Code Reviewer**: Quality and best practices audit
- **Security Auditor**: OWASP Top 10 vulnerability scanning

### Skills
- **API Generator**: RESTful API endpoints with validation
- **UI Builder**: Accessible, responsive components
- **Database Schema**: Schema design and migrations

### Steering Documents
- **Product Vision**: Template for product documentation
- **Tech Stack**: Technology decisions and architecture
- **Project Structure**: File organization and conventions

## Installation

No installation required! Use npx to run commands directly:

```bash
npx @incidental/project-templates <command>
```

## Quick Start

### 1. Initialize Your Project

Run the interactive setup wizard in your project directory:

```bash
npx @incidental/project-templates init
```

This will:
- Auto-detect your framework (Next.js, React, or vanilla JS)
- Prompt you to select which templates to install
- Copy selected templates to your `.claude/` directory

### 2. Use Claude Code

Start Claude Code in your project:

```bash
claude
```

### 3. Try Your New Commands

Use your installed commands:

```bash
/create-page dashboard
/create-api-route users
/run-tests
```

## CLI Commands

### `init`

Interactive setup wizard to install templates.

```bash
npx @incidental/project-templates init

# Skip prompts and install all templates
npx @incidental/project-templates init --yes

# Specify framework manually
npx @incidental/project-templates init --framework nextjs
```

### `add-command <name>`

Install a specific command template.

```bash
# Auto-detect framework
npx @incidental/project-templates add-command create-page

# Specify framework
npx @incidental/project-templates add-command create-component --framework react
```

### `add-agent <name>`

Install a specific agent template.

```bash
# Auto-detect framework
npx @incidental/project-templates add-agent nextjs-expert

# Specify framework
npx @incidental/project-templates add-agent react-expert --framework react
```

### `add-skill <name>`

Install a specific skill template.

```bash
npx @incidental/project-templates add-skill api-generator
npx @incidental/project-templates add-skill ui-builder
```

### `list`

List all available templates.

```bash
# List all templates
npx @incidental/project-templates list

# Filter by type
npx @incidental/project-templates list --type commands
npx @incidental/project-templates list --type agents

# Filter by framework
npx @incidental/project-templates list --framework nextjs
```

### `update`

Update installed templates to latest version (coming soon).

```bash
npx @incidental/project-templates update
```

## Available Templates

### Commands

#### Next.js
- `create-page` - Create new App Router pages
- `create-api-route` - Create API route handlers
- `optimize-images` - Convert to next/image

#### React
- `create-component` - Create TypeScript components
- `add-state-management` - Add state management

#### Vanilla JavaScript
- `create-module` - Create ES6 modules

#### Shared (All Frameworks)
- `run-tests` - Execute test suite
- `generate-docs` - Generate documentation

### Agents

#### Framework-Specific
- `nextjs-expert` - Next.js specialist
- `react-expert` - React specialist

#### Shared
- `test-runner` - Automated testing
- `code-reviewer` - Code quality audits
- `security-auditor` - Security scanning

### Skills

- `api-generator` - RESTful API endpoints
- `ui-builder` - UI components
- `database-schema` - Database design

## Framework Detection

The CLI automatically detects your framework by checking:

### Next.js Detection
- `next` in dependencies
- `next.config.js` or similar config files
- `app/` or `pages/` directory

### React Detection
- `react` in dependencies (without Next.js)
- `src/App.jsx` or `src/App.tsx`
- Vite or Create React App structure

### Vanilla JavaScript
- No framework dependencies detected
- Standalone HTML/JS/CSS files

## Project Structure

After installation, your project will have:

```
your-project/
├── .claude/
│   ├── commands/           # Custom slash commands
│   │   ├── create-page.md
│   │   ├── create-api-route.md
│   │   └── ...
│   ├── agents/             # Custom agents
│   │   ├── nextjs-expert.md
│   │   ├── test-runner.md
│   │   └── ...
│   ├── skills/             # Skills
│   │   ├── api-generator/
│   │   │   └── SKILL.md
│   │   └── ...
│   └── steering/           # Steering documents
│       ├── product.md
│       ├── tech.md
│       └── structure.md
├── src/
├── package.json
└── ...
```

## Usage Examples

### Create a New Next.js Page

```bash
# In Claude Code
/create-page about

# Creates: src/app/about/page.tsx with metadata and TypeScript
```

### Generate an API Endpoint

```bash
# In Claude Code
/create-api-route auth/login

# Creates: src/app/api/auth/login/route.ts with validation
```

### Create a React Component

```bash
# In Claude Code
/create-component Button

# Creates: src/components/Button.tsx with TypeScript and props
```

### Run Tests

```bash
# In Claude Code
/run-tests

# Executes test suite, analyzes failures, offers to fix
```

## Requirements

- Node.js 18 or higher
- npm 9 or higher
- Claude Code CLI installed
- JavaScript/TypeScript project

## How It Works

1. **Detection**: CLI scans your `package.json` and file structure
2. **Selection**: You choose which templates to install (or use `--yes` for all)
3. **Installation**: Templates are copied to `.claude/` directory
4. **Usage**: Claude Code automatically recognizes the templates

## Best Practices

- Run `init` at the start of new projects
- Use framework-specific templates for better results
- Review templates and customize for your needs
- Keep templates updated with `update` command
- Share `.claude/` directory with your team via git

## Customization

All installed templates are regular Markdown files in your `.claude/` directory. You can:

- Edit templates to match your coding style
- Add project-specific instructions
- Create new templates based on existing ones
- Remove templates you don't need

## Contributing

We welcome contributions! To add new templates:

1. Fork the repository
2. Create templates in the appropriate directory
3. Test your templates in real projects
4. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## Roadmap

- [ ] More framework support (Vue, Angular, Svelte)
- [ ] Community template marketplace
- [ ] Template versioning and rollback
- [ ] Interactive template customization
- [ ] VS Code extension integration
- [ ] Template analytics and usage stats

## License

MIT © [Incidental](https://github.com/incidental)

## Support

- 📖 [Documentation](https://github.com/incidental/project-templates#readme)
- 🐛 [Issue Tracker](https://github.com/incidental/project-templates/issues)
- 💬 [Discussions](https://github.com/incidental/project-templates/discussions)

## Related

- [Claude Code](https://claude.ai/code) - Official Claude Code CLI
- [Claude Code Docs](https://code.claude.com/docs) - Claude Code documentation

---

Made with ❤️ for the Claude Code community