@untools/starter

A powerful CLI tool to scaffold production-ready TypeScript projects with GraphQL, Express, MongoDB, and Next.js.

🚀 Overview

@untools/starter helps you jump-start development by quickly scaffolding fully-configured TypeScript projects with modern stack technologies. Choose between:

• API: Robust GraphQL API powered by Express and MongoDB
• Frontend: Feature-rich Next.js frontend with authentication and GraphQL client
• Fullstack: Integrated API and frontend combo with preconfigured connections

Skip the hours of project setup and dive straight into building what matters.

✨ Features

Backend API Features

• TypeScript: Full type safety with modern TypeScript configuration
• Express & Apollo Server: Industry-standard GraphQL server setup
• MongoDB Integration: Preconfigured with Mongoose models and connections
• Authentication System: Complete JWT-based auth with refresh tokens
• OAuth Integration: Ready-to-use Google authentication flow
• Role-Based Access Control: Built-in user permission system
• Email Services: Integrated Nodemailer and optional Resend.com support
• API Key Management: Secure key generation and validation system
• Password Reset Flow: Complete secure reset functionality
• Web Push Notifications: VAPID key generation and notification endpoints
• Payment Gateway: Optional payment processing integration
• AI Ready: Optional Google Gemini AI API configuration
• Smart Port Allocation: Consistent project-specific ports via @untools/port-gen
• Container Ready: Optional Docker and docker-compose configurations
• Environment Setup: Automatically configured .env files with secure generated secrets

Frontend Features

• Next.js 15: Modern React with App Router architecture
• TypeScript: End-to-end type safety with GraphQL codegen
• Multiple Templates:
  • GraphQL Client: Apollo Client with automatic type generation
  • Fullstack: MongoDB-based authentication with JWT, Magic Link, and OTP
• Authentication UI: Complete login/signup flows and protected routes
• Responsive Design: Mobile-friendly layouts using Tailwind CSS
• State Management: Preconfigured global state with Zustand
• File Uploads: Optional Cloudinary media integration
• Push Notifications: Browser notification support

Fullstack Setup

• Monorepo Configuration: Preconfigured workspace for simultaneous development
• Connected Services: API and frontend pre-wired to work together
• Unified Commands: Single command to run both services
• Type Sharing: Full type safety between backend and frontend

📦 Installation

# Install globally
npm install -g @untools/starter

# Or use with npx (no installation needed)
npx @untools/starter my-project

🛠️ Usage

Interactive Mode

# Create an API project
@untools/starter starter --type api

# Create a Next.js frontend
@untools/starter my-client --type frontend

# Create a full-stack project
@untools/starter my-app --type fullstack

The CLI will guide you through configuration options with interactive prompts.

Quick Start Mode

# Create with default settings
@untools/starter my-project --type api --yes
@untools/starter my-project --type frontend --yes
@untools/starter my-project --type fullstack --yes

Command Options

| Option | Alias | Description | Default | | -------- | ----- | ----------------------------------------------- | ------- | | --type | -t | Project type: api, frontend, or fullstack | api | | --yes | -y | Skip all prompts and use defaults | false |

⚙️ Configuration Options

The interactive setup offers extensive customization:

API Project Options

• Basic Configuration:

  • Application name and port
  • Docker integration toggle

• Feature Selection:

  • MongoDB database configuration
  • Email service integration
  • Google OAuth authentication
  • Payment gateway services
  • Google Gemini AI integration
  • Web Push notification support

Frontend Project Options

• Template Selection:

  • GraphQL Client: Apollo-based frontend with GraphQL API integration
  • Fullstack: Self-contained authentication with MongoDB, JWT, Magic Link, and OTP

• GraphQL Template Options:

  • API Connectivity (GraphQL API URL configuration)
  • Cloudinary for media uploads
  • Google OAuth credentials
  • Web Push notifications setup

• Fullstack Template Options:

  • MongoDB connection configuration
  • Email service for Magic Link and OTP (Resend integration)
  • PayID OAuth integration (optional)
  • JWT and encryption key generation

Fullstack Project Options

All of the above options plus integrated workspace configuration.

📱 Fullstack Template Deep Dive

The Fullstack Next.js template (aevrHQ/next-starter) provides a complete authentication system with multiple authentication methods, perfect for building production-ready applications without external API dependencies.

Authentication Methods

1. Email/Password Authentication

   • Traditional login with JWT-based sessions
   • Secure password hashing and validation
   • Session management with encrypted tokens

2. Magic Link Authentication

   • Passwordless login via email
   • Time-limited secure tokens
   • One-click authentication flow

3. OTP (One-Time Password)

   • Email-based verification codes
   • Configurable expiration times
   • Secure code generation and validation

4. PayID OAuth Integration (Optional)

   • Third-party authentication via PayID
   • KYC verification support
   • User information retrieval

Key Features

• MongoDB Integration: Direct database connection with Mongoose models
• Session Management: JWT-based sessions with encryption
• Email Service: Multi-provider support (Resend, Nodemailer, Zoho)
• Security: Automatic generation of encryption keys and secrets
• UI Components: Pre-built authentication forms and protected routes
• Middleware: Route protection and session validation

Environment Variables

The template automatically configures:

• MONGO_URI - MongoDB connection string
• ENCRYPTION_KEY - 32-byte encryption key for sensitive data
• APP_NAME - Your application name
• MAIL_USER - Email address for sending authentication emails
• MAIL_PASS - Email password (for SMTP)
• MAIL_LOGO - Logo URL for email templates
• APP_SUPPORT_MAIL - Support email address
• RESEND_API_KEY - Resend API key (recommended)
• DEFAULT_MAIL_PROVIDER - Email provider selection (resend/nodemailer)
• ZOHO_KEY - Zoho mail API key (optional)

PayID OAuth (if enabled):

• PAYID_API_URL - PayID API endpoint
• OAUTH_CLIENT_ID - OAuth client ID
• OAUTH_CLIENT_SECRET - OAuth client secret
• ORG_ID - Organization ID
• REDIRECT_URL - OAuth callback URL

Project Structure

next-starter/
├── app/
│   ├── (app)/                # Protected application routes
│   │   ├── dashboard/        # Main dashboard
│   │   └── layout.tsx        # App layout with sidebar
│   ├── (auth)/               # Authentication routes
│   │   ├── login/            # Login page
│   │   ├── register/         # Registration page
│   │   └── auth/             # Auth callbacks
│   ├── api/v1/               # API routes
│   │   ├── auth/             # Authentication endpoints
│   │   │   ├── login/
│   │   │   ├── register/
│   │   │   ├── logout/
│   │   │   ├── magic-link/
│   │   │   ├── otp/
│   │   │   └── session/
│   │   └── payid/            # PayID OAuth endpoints
│   └── callback/             # OAuth callbacks
├── components/
│   ├── Auth/                 # Authentication components
│   ├── ui/                   # UI components (shadcn/ui)
│   └── providers/            # Context providers
├── lib/
│   ├── models/               # MongoDB models
│   ├── session.ts            # Session management
│   ├── crypto.ts             # Encryption utilities
│   └── mongodb.ts            # Database connection
└── utils/
    ├── auth/                 # Auth utilities
    ├── email/                # Email service
    └── payid/                # PayID integration

Getting Started with Fullstack Template

# Create a new project with Fullstack template
npx @untools/starter my-app --type frontend

# Select "Fullstack" when prompted
# Configure MongoDB and email service

# Install dependencies
cd my-app
npm install

# Start MongoDB (if running locally)
# mongod

# Run the development server
npm run dev

The application will be available at http://localhost:3030 with authentication routes ready to use.

🔐 Security Features

@untools/starter automatically generates:

• Cryptographically secure random tokens for JWT authentication
• Webhook signature verification secrets
• API keys with secure generation patterns
• VAPID public/private keypairs for Push API
• Session secrets for Next.js
• MongoDB connection strings

🏗️ Generated Project Structure

API Project

starter/
├── src/
│   ├── config/               # Configuration management
│   ├── graphql/              # GraphQL schema and resolvers
│   │   ├── typeDefs/         # GraphQL type definitions
│   │   ├── resolvers/        # GraphQL resolvers
│   ├── middlewares/          # Express middleware functions
│   ├── models/               # Mongoose data models
│   ├── services/             # Business logic layer
│   ├── utils/                # Helper functions
│   ├── index.ts              # Application entry point
├── .env                      # Environment variables (pre-configured)
├── tsconfig.json             # TypeScript configuration
├── package.json              # Dependencies and scripts
├── README.md                 # Generated documentation
└── [Docker files]            # Optional Docker configuration

Frontend Project

starter/
├── app/                      # Next.js App Router structure
├── components/               # Reusable UI components
├── lib/                      # Utility functions and hooks
├── graphql/                  # GraphQL queries and mutations
├── styles/                   # Global CSS and Tailwind config
├── public/                   # Static assets
├── .env.local                # Environment configuration
├── codegen.ts                # GraphQL code generation config
├── package.json              # Dependencies and scripts
└── README.md                 # Generated documentation

Fullstack Project

starter/
├── my-app-api/               # API project (structure as above)
├── my-app-client/            # Frontend project (structure as above)
├── package.json              # Workspace configuration
└── README.md                 # Project documentation

🧠 Philosophy

@untools/starter follows these principles:

1. Zero Configuration: Works out of the box with sensible defaults
2. Full Flexibility: Extensive customization when you need it
3. Production Ready: Security-focused with best practices built in
4. Developer Experience: Optimized for rapid development and maintenance

🤝 Contributing

Contributions are welcome! To contribute:

# Clone the repository
git clone https://github.com/miracleonyenma/untools-starter.git

# Install dependencies
cd untools-starter
npm install

# Run in development mode
npm run dev

📄 License

MIT © Miracle Onyenma

🙏 Acknowledgements

This project uses:

• miracleonyenma/express-ts-graphql-starter as the API template
• aevrHQ/express-ts-postgres-graphql-starter for PostgreSQL API template
• miracleonyenma/nextjs-starter-client for the Next.js GraphQL template
• aevrHQ/next-starter for the Next.js Fullstack template
• @untools/port-gen for consistent port allocation
• degit for template scaffolding