STLabs Start

A CLI tool for generating projects with predefined boilerplates, downloading templates from GitHub and configuring variables automatically based on the selected stack.

Features

• 🚀 Simple: Each template is a complete, functional project
• 🔧 Flexible: Automatic variable configuration per stack
• 📦 Maintainable: Independent, easy-to-update templates
• 🎯 Interactive: Intuitive developer experience

Installation

npm install -g stlabs-start

Or use directly with npx:

npx stlabs-start

Usage

Interactive Mode

npx stlabs-start

With Parameters

npx stlabs-start my-project nextjs-nextauth-postgres

Advanced Options

# List available templates
npx stlabs-start --list

# Show template information
npx stlabs-start --info nextjs-nextauth-postgres

# Use configuration file
npx stlabs-start my-project --config config.json

# Update templates cache
npx stlabs-start --update

System Health Check

# Check if your environment has all required tools
npx stlabs-start doctor

Verifies: Node.js version, GitHub authentication, template cache, network connectivity, and repository access.

Templates can also declare their own requirements (e.g. docker, python, flutter). When you select a template, the CLI automatically checks if the required tools are installed before proceeding.

GitHub Authentication (for private templates)

# Setup GitHub token for private repositories
npx stlabs-start auth

# View current authentication
npx stlabs-start auth --view

# Clear authentication
npx stlabs-start auth --clear

Environment Variables:

# Set GitHub token via environment variable
export GITHUB_TOKEN=ghp_your_token_here
# or
export GH_TOKEN=ghp_your_token_here

🎯 Quick Start

# Create a new project interactively
npx stlabs-start

# Create project with specific template
npx stlabs-start my-app nextjs-nextauth-postgres

# List available templates
npx stlabs-start --list

Interactive Flow

1. Select Project Type: Choose between Fullstack, Backend, Frontend, Mobile, and more
2. Choose Template: Select from available templates for your chosen category
3. Check Requirements: Automatically verifies required system tools are installed
4. Configure Variables: Set up project-specific variables
5. Generate Project: Your project is created and dependencies are installed

📋 Available Commands

| Command | Description | |---------|-------------| | stlabs-start [project] [template] | Create new project | | stlabs-start --list | List available templates | | stlabs-start --info <template> | Show template details | | stlabs-start --update | Update template cache | | stlabs-start auth | Configure GitHub authentication | | stlabs-start --search <keyword> | Search templates by keyword | | stlabs-start doctor | Check system health and dependencies |

🎨 Available Templates

Templates are loaded from s-tlabs/boilerplates and organized by category:

🚀 Fullstack Templates

• nextjs-nextauth-postgres - Next.js + NextAuth + PostgreSQL
• nextjs-clerk-supabase - Next.js + Clerk + Supabase

⚙️ Backend Templates

• nestjs-jwt-postgres - NestJS + JWT + PostgreSQL
• express-mongodb - Express + MongoDB

🎨 Frontend Templates

• react-vite-tailwind - React + Vite + Tailwind CSS
• vue-nuxt - Vue + Nuxt 3
• svelte-kit - SvelteKit

More templates coming soon...

Development

# Clone the repository
git clone <repository-url>
cd stlabs-start

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

Project Structure

src/
├── commands/
│   ├── create.ts              # Main create command
│   ├── list.ts                # List available templates
│   ├── info.ts                # Show template details
│   ├── update.ts              # Update template cache
│   ├── auth.ts                # GitHub authentication
│   └── doctor.ts              # System health check
├── managers/
│   ├── template-manager.ts    # Template fetching & caching
│   ├── github-manager.ts      # GitHub archive download
│   ├── config-manager.ts      # Configuration & variables
│   ├── auth-manager.ts        # Token management
│   └── requirements-checker.ts # System dependency checks
├── utils/
│   └── validators.ts          # Input validation
├── __tests__/                 # Test suites
└── index.ts                   # CLI entry point

Configuration

You can provide a configuration file to skip interactive prompts:

{
  "projectName": "my-app",
  "projectDescription": "My awesome application",
  "authorName": "John Doe",
  "authorEmail": "[email protected]",
  "template": "nextjs-nextauth-postgres",
  "nextauthSecret": "your-secret-here",
  "databaseUrl": "postgresql://user:pass@localhost:5432/myapp"
}

CI/CD

The project uses GitHub Actions for continuous integration and automated publishing.

CI Pipeline (.github/workflows/ci.yml)

Runs automatically on every push and pull request to main:

• Builds and tests across Node.js 18, 20, and 22
• Ensures TypeScript compiles without errors
• Runs all test suites

Automated npm Publishing (.github/workflows/publish.yml)

Publishes to npm automatically when a GitHub Release is created, using OIDC Trusted Publishing (no tokens needed):

1. Builds the project
2. Runs all tests
3. Publishes to npm with provenance attestation via OIDC

Setup (one-time)

Configure Trusted Publishing on npmjs.com:

1. Go to npmjs.com/package/stlabs-start/access
2. Under Trusted Publishers, click Add trusted publisher
3. Fill in:
   • Organization/Owner: s-tlabs
   • Repository: stlabs-start
   • Workflow filename: publish.yml
   • Environment: (leave empty)
4. Save

No NPM_TOKEN secret is needed. The workflow uses OIDC to authenticate directly with npm.

Publishing a new version

# 1. Update version in package.json and src/index.ts
npm version patch   # or minor, or major

# 2. Push the version commit and tag
git push && git push --tags

# 3. Create a Release on GitHub from the tag
#    The publish workflow will run automatically

Alternatively, create a release directly from the GitHub UI:

• Go to Releases → Draft a new release
• Choose the tag (or create a new one)
• Click "Publish release" → npm publish runs automatically with provenance

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 Creating Templates

See templates.md for detailed instructions on creating your own templates.

🐛 Issues & Support

• 🐛 Report bugs
• 💬 Ask questions
• 💡 Request features

📊 Stats

📄 License

MIT © STLabs