# project-init

> Initialize new project with best practices. Sets up package manager, linting, formatting, testing, and git configuration. Use when starting a new project.

- Author: Edison
- Repository: soilmass/claudeutils
- Version: 20260127023329
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/soilmass/claudeutils
- Web: https://mule.run/skillshub/@@soilmass/claudeutils~project-init:20260127023329

---

---
name: project-init
description: >-
  Initialize new project with best practices. Sets up package manager,
  linting, formatting, testing, and git configuration. Use when starting
  a new project.
license: MIT
compatibility: >-
  npm, pnpm, yarn, bun; TypeScript, JavaScript, Python, Go; React, Vue, Express, FastAPI
metadata:
  version: "1.0.0"
  category: scaffolding
  ecosystem: universal
---

# Project Init

Initialize a new project with best practices.

## Task

Set up new project:
- Package manager and dependencies
- TypeScript/language configuration
- Linting and formatting
- Testing framework
- Git configuration
- Editor settings

## Instructions

1. **Determine Project Type**
   - Library (npm package)
   - Application (web, API, CLI)
   - Full-stack (frontend + backend)

2. **Choose Technology Stack**
   - Language: TypeScript, JavaScript, Python, Go
   - Framework: React, Vue, Express, FastAPI
   - Build tool: Vite, esbuild, Rollup

3. **Initialize Package Manager**
   ```bash
   # Detect preferred manager
   npm init -y
   # or
   pnpm init
   # or
   bun init
   ```

4. **Set Up Configuration**
   - tsconfig.json
   - ESLint + Prettier
   - Testing framework
   - Git hooks

5. **Create Directory Structure**
   Standard layout for project type

6. **Initialize Git**
   - .gitignore
   - Initial commit

## Output Format

```markdown
## Project Initialized

### Project Details
| Setting | Value |
|---------|-------|
| Name | my-project |
| Type | Library |
| Language | TypeScript |
| Package Manager | pnpm |

### Files Created

```
my-project/
├── src/
│   └── index.ts
├── tests/
│   └── index.test.ts
├── .github/
│   └── workflows/
│       └── ci.yml
├── package.json
├── tsconfig.json
├── .eslintrc.cjs
├── .prettierrc
├── vitest.config.ts
├── .gitignore
├── .editorconfig
├── LICENSE
└── README.md
```

### Configuration Files

#### package.json
```json
{
  "name": "my-project",
  "version": "0.0.1",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest",
    "lint": "eslint src --ext .ts",
    "format": "prettier --write src",
    "prepare": "husky install"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0",
    "husky": "^9.0.0"
  }
}
```

#### tsconfig.json
```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

#### .eslintrc.cjs
```javascript
module.exports = {
  root: true,
  env: { node: true },
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    '@typescript-eslint/explicit-function-return-type': 'warn'
  }
};
```

### Dependencies Installed
| Package | Version | Purpose |
|---------|---------|---------|
| typescript | 5.3.3 | Language |
| vitest | 1.2.0 | Testing |
| eslint | 8.56.0 | Linting |
| prettier | 3.2.0 | Formatting |

### Git Configuration
- .gitignore created
- Husky hooks installed
- Initial commit created

### Next Steps

1. **Install dependencies:**
   ```bash
   pnpm install
   ```

2. **Start development:**
   ```bash
   pnpm dev
   ```

3. **Configure CI:** (already set up)
   - Push to GitHub to trigger CI

4. **Customize settings:**
   - Edit tsconfig.json for your needs
   - Add dependencies as needed
```

## Example Usage

Initialize new project:
```
/project-init my-project
```

Initialize with specific type:
```
/project-init --type library my-lib
```

Initialize with framework:
```
/project-init --framework react my-app
```

Initialize minimal:
```
/project-init --minimal my-project
```

## Project Types

| Type | Structure | Use Case |
|------|-----------|----------|
| library | src/, dist/ | npm package |
| app | src/, public/ | Web application |
| api | src/routes/, src/services/ | REST API |
| cli | src/commands/, bin/ | CLI tool |
| fullstack | packages/ | Monorepo |

## Project Structure by Ecosystem

### Node.js/TypeScript
```
project/
├── src/
│   └── index.ts
├── tests/
│   └── index.test.ts
├── dist/
├── package.json
├── tsconfig.json
├── .eslintrc.cjs
├── .prettierrc
└── vitest.config.ts
```

### Python
```
project/
├── src/
│   └── myproject/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── pyproject.toml
├── setup.cfg
├── .python-version
├── requirements.txt
├── requirements-dev.txt
└── README.md
```

**pyproject.toml (Python)**
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "myproject"
version = "0.1.0"
description = "My Python project"
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
dependencies = []

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=4.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
    "black>=24.0",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=src/myproject --cov-report=term-missing"

[tool.ruff]
target-version = "py311"
line-length = 88
select = ["E", "F", "I", "N", "W", "UP"]

[tool.mypy]
python_version = "3.11"
strict = true

[tool.black]
line-length = 88
target-version = ["py311"]
```

### Go
```
project/
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   └── handler/
│       └── handler.go
├── pkg/
│   └── utils/
│       └── utils.go
├── api/
├── configs/
├── go.mod
├── go.sum
├── Makefile
└── README.md
```

**go.mod (Go)**
```go
module github.com/username/myproject

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/stretchr/testify v1.8.4
)
```

**Makefile (Go)**
```makefile
.PHONY: build test lint run clean

build:
	go build -o bin/myapp ./cmd/myapp

test:
	go test -v -race -coverprofile=coverage.out ./...

lint:
	golangci-lint run ./...

run:
	go run ./cmd/myapp

clean:
	rm -rf bin/ coverage.out
```

## Templates

### Library
- TypeScript + declaration files
- Vitest for testing
- Rollup/esbuild for bundling
- Changesets for versioning

### Web App
- React/Vue + TypeScript
- Vite for dev/build
- Testing Library
- CSS/Tailwind

### API
- Express/Fastify + TypeScript
- Validation (Zod)
- Database (Prisma)
- Auth (JWT)

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `Directory already exists` | Target project directory is not empty | Choose different name or use `--force` to overwrite |
| `Package manager not found` | npm/pnpm/yarn/bun not installed | Install the required package manager first |
| `Git not initialized` | Git command failed or not installed | Install git and ensure it's in PATH |
| `Template not found` | Invalid project type specified | Use valid type: library, app, api, cli, fullstack |
| `Permission denied` | Cannot write to target directory | Check directory permissions or run with elevated access |

```
ERROR: INPUT
  what: Directory 'my-project' already exists
  where: ./my-project
  fix: Use --force flag or choose a different project name
```

```
ERROR: NOTFOUND
  what: Package manager 'pnpm' not found
  where: system PATH
  fix: Install pnpm with 'npm install -g pnpm' or use --pm npm
```

```
ERROR: VALIDATION
  what: Invalid project type 'invalid'
  where: --type argument
  fix: Use one of: library, app, api, cli, fullstack
```