Frequently Asked Questions

What is Kickstart Express?

Kickstart Express is a powerful CLI tool that helps you quickly scaffold Express.js projects with modern tooling and best practices. It supports both TypeScript and JavaScript, offers multiple project templates, and includes optional Docker configuration.

Why use Kickstart Express instead of creating projects manually?

Kickstart Express saves you time by providing:

• Pre-configured project structures with best practices
• Automatic dependency management and setup
• Multiple template options for different use cases
• Docker support for containerized development
• TypeScript configuration that just works
• Consistent project structure across your organization

Is Kickstart Express free to use?

Yes! Kickstart Express is completely free and open-source. It's released under the ISC license, which means you can use it for personal and commercial projects without any restrictions.

What's the difference between interactive and non-interactive mode?

Interactive mode (default) guides you through project configuration with prompts, making it perfect for beginners or when you want to explore options.

Non-interactive mode allows you to specify all options via command-line arguments, ideal for automation, scripts, or when you know exactly what you want.

# Interactive
kickstart-express

# Non-interactive
kickstart-express --name my-api --language ts --docker --structured

Do I need to install Kickstart Express globally?

No, you have two options:

npm install -g kickstart-express

npx kickstart-express

What Node.js version do I need?

Kickstart Express requires Node.js version 18.0.0 or higher. You can check your version with:

node --version

If you need to update Node.js, visit nodejs.orgor use a version manager like nvm.

Can I use npm instead of pnpm?

Yes! While the generated projects use pnpm by default (for faster installs), you can use any package manager. The generated package.json works with npm, yarn, and pnpm.

# Using npm
cd my-project
npm install
npm run dev

# Using yarn
cd my-project  
yarn install
yarn dev

I'm getting permission errors on macOS/Linux. What should I do?

This usually happens when installing globally. Try one of these solutions:

npx kickstart-express

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Which template should I choose?

Choose based on your project size and complexity:

• Simple: Perfect for learning, prototypes, or small APIs
• Src folder: Good for medium-sized projects that need organization
• Structured: Best for large applications, teams, or production use

See our Project Templates guide for detailed comparisons.

What's included in the structured template?

The structured template includes:

• Separation of concerns (controllers, services, routes, models)
• A working calculator API example
• Proper TypeScript types and interfaces
• Best practices for error handling
• Scalable architecture patterns

Can I modify the generated project?

Absolutely! The generated project is completely yours to modify. Kickstart Express just gives you a solid starting point. You can add dependencies, change the structure, add new features, or modify anything to fit your needs.

Should I use TypeScript or JavaScript?

We recommend TypeScript for most projects because it provides:

• Better IDE support with autocomplete and error detection
• Compile-time error checking
• Better refactoring capabilities
• Improved code documentation through types

Choose JavaScript if you're just learning or need to get something running quickly without the TypeScript learning curve.

When should I use the Docker option?

Use Docker when you:

• Want consistent development environments across your team
• Plan to deploy to containerized platforms (Kubernetes, Docker Swarm)
• Are building microservices
• Want to isolate your application dependencies

Do I need Docker installed to use the Docker template?

No, you can generate a project with Docker files without having Docker installed. However, you'll need Docker installed to actually build and run the containerized application.

# Generate with Docker files (no Docker needed)
kickstart-express --name my-api --docker

# Build and run (requires Docker)
cd my-api
docker-compose up --build

How do I deploy my generated project?

The generated projects are ready for deployment to various platforms:

• Heroku: Push to git, add Procfile if needed
• Vercel/Netlify: Works with minor adjustments for serverless
• DigitalOcean/AWS: Use the included Docker configuration
• Traditional VPS: Run npm build && npm start

The command "kickstart-express" is not found

This usually means the package isn't installed globally or your PATH isn't configured correctly. Try:

# Use npx instead (recommended)
npx kickstart-express

# Or install globally
npm install -g kickstart-express

# Check if it's installed
npm list -g kickstart-express

"Directory already exists" error

This happens when you try to create a project with a name that already exists in the current directory. Choose a different name or remove the existing directory:

# Use a different name
kickstart-express --name my-api-v2

# Or remove the existing directory (be careful!)
rm -rf existing-project
kickstart-express --name existing-project

Generated project won't start

First, make sure you've installed dependencies and check for error messages:

cd your-project

# Install dependencies
pnpm install  # or npm install

# Check for TypeScript errors (TS projects only)
pnpm build    # or npm run build

# Start development server
pnpm dev      # or npm run dev

If you're still having issues, check that port 3000 isn't already in use or set a different port in your .env file.

I found a bug or have a feature request

We appreciate feedback! Please:

• Check existing issues first
• Create a new issue with detailed information
• Include your Node.js version, OS, and steps to reproduce
• For feature requests, explain the use case and benefits

Can I use Kickstart Express in CI/CD pipelines?

Yes! It's perfect for automated project generation. Use non-interactive mode:

# In your CI script
npx kickstart-express --name $SERVICE_NAME --language ts --docker --structured

# Or create a script for your team
#!/bin/bash
npx kickstart-express --name "$1" --language ts --docker --structured
cd "$1" && pnpm install && pnpm build

Can I customize the templates?

While you can't customize templates directly, you can:

• Generate a project and modify it as needed
• Create your own wrapper script with post-generation customizations
• Fork the project and modify templates for your organization
• Request new templates via feature requests

How do I integrate with my team's development workflow?

Several approaches work well:

• Add kickstart-express to your team's setup documentation
• Create npm scripts that wrap kickstart-express with your preferred options
• Use it in project templates or yeoman generators
• Include it in development environment setup scripts

Is there an API for programmatic usage?

Yes! While primarily a CLI tool, you can use it programmatically in Node.js applications. See our API Reference for details.

const { generateProject } = require('kickstart-express');

await generateProject({
  name: 'my-api',
  language: 'ts',
  structured: true
});

How can I contribute to Kickstart Express?

We welcome all kinds of contributions! Check out our Contributing Guidefor detailed information on:

• Reporting bugs and requesting features
• Improving documentation
• Adding new templates or features
• Helping with testing and code review

Where can I get help or discuss ideas?

Join our community:

• GitHub Issues for bugs and feature requests
• GitHub Discussions for questions and ideas
• This documentation site for guides and examples

Will you add support for other frameworks (Fastify, Koa, etc.)?

While Kickstart Express focuses on Express.js, we're open to expanding support based on community demand. If you're interested in other frameworks, please create a feature request explaining your use case!