create-atk-template-typespec-basic

A scaffolding tool for creating TypeSpec API projects with Azure Toolkit (ATK) integration.

Features

• 🚀 Quick project setup with interactive prompts
• 📝 TypeSpec-based API definitions
• 🎨 Optional custom actions support
• 📦 Automatic dependency installation with npm
• 🔄 Git repository initialization
• ✨ Clean, production-ready project structure

Usage

Using npx (Recommended)

The easiest way to create a new project:

npx create-atk-template-typespec-basic my-project

Using npm create

Alternative shorthand syntax:

npm create atk-template-typespec-basic my-project

Interactive Mode

Run without a project name to enter interactive mode:

npx create-atk-template-typespec-basic

Follow the prompts to configure your project:

• Project Name: Enter a valid npm package name
• Custom Actions: Choose whether to include custom action templates
• Git Repository: Initialize a git repository

Non-Interactive Mode

Specify all options via command line flags:

npx create-atk-template-typespec-basic my-api-project --custom-actions --git

Command Line Options

npx create-atk-template-typespec-basic [project-name] [options]

Options:
  --custom-actions    Include custom actions in the template
  --no-custom-actions Skip custom actions
  --git              Initialize git repository (default: true)
  --no-git           Skip git initialization
  --skip-install     Skip dependency installation
  -h, --help         Display help
  -v, --version      Display version

Generated Project Structure

my-api-project/
├── src/
│   ├── main.tsp           # Main TypeSpec definition
│   ├── models/            # Data models
│   │   └── common.tsp
│   └── custom-actions/    # (Optional) Custom actions
│       ├── create-user.tsp
│       └── update-user.tsp
├── tspconfig.yaml         # TypeSpec configuration
├── package.json
├── README.md
├── .gitignore
└── .github/
    └── workflows/
        └── ci.yml         # CI/CD workflow

Generated Project Scripts

After creating your project, you can use:

npm run compile    # Compile TypeSpec to OpenAPI
npm run watch      # Watch mode for development
npm run format     # Format TypeSpec files
npm run lint       # Lint TypeSpec files

Requirements

• Node.js >= 18.0.0
• npm, yarn, or pnpm

What is TypeSpec?

TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Learn more at typespec.io.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

The project uses:

• GitHub Actions for CI/CD (see SETUP_CHECKLIST.md)
• release-please for automated releases (see RELEASE_MANAGEMENT.md)
• Conventional Commits for version management

Commit Message Format

This project uses Conventional Commits for automated releases:

feat: add new feature        # triggers minor version bump (1.X.0)
fix: correct bug             # triggers patch version bump (1.0.X)
feat!: breaking change       # triggers major version bump (X.0.0)

See RELEASE_MANAGEMENT.md for complete documentation.

Development

Local Development

1. Clone the repository
2. Install dependencies: npm install
3. Build: npm run build
4. Test locally: npm link && create-atk-template-typespec-basic test-project

Publishing

This project uses release-please for automated releases:

1. Commit changes using conventional commits
2. Push to the main branch
3. release-please creates a Release PR with updated version and changelog
4. Review and merge the Release PR
5. Package is automatically published to npm

See RELEASE_MANAGEMENT.md for detailed release workflow.

License

MIT © Microsoft