Getting Started

Your First Project

Follow these steps to create and run your first application

Create Your Project

Run the CLI and follow the interactive wizard

bunx @noundryfx/ndts-cli init

You'll be asked to configure:

• Project name: my-app
• Database: SQLite / PostgreSQL / MySQL
• Authentication: Custom JWT / Better Auth / Auth.js / Auth0
• Email provider: Resend / SendGrid / SMTP / None
• Optional features: Caching, Blob Storage, Queues, Logging, Telemetry

Navigate to Your Project

Change into your newly created project directory

cd my-app

Set Up Environment

Copy the environment template and configure your secrets

cp .env.example packages/server/.env

Edit packages/server/.env:

# Server
PORT=3001
NODE_ENV=development

# Database (SQLite)
DB_URL=file:local.db

# Auth
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=http://localhost:3000

Start Development Servers

Launch both the API server and frontend with automatic Docker service startup

bun run dev

🐳 Automatic Docker Service Startup

When you run bun run dev, Docker containers automatically start for your selected services:

✓ Checks if Docker is running
✓ Starts only required services (PostgreSQL, MySQL, Redis, MinIO, Jaeger, MailHog)
✓ Waits for services to be ready
✓ Displays connection URLs and credentials
✓ Starts your application
✓ Gracefully handles Docker not being available

🔌 Server Running:

http://localhost:3001

API endpoints available

💻 Frontend Running:

http://localhost:3000

Open in browser

Test Your Application

Open your browser and interact with your new app

✓ What you'll see:

• Homepage with navigation
• User registration page
• Login page with authentication
• Protected dashboard (requires login)

🧪 Try it out:

Click "Register" and create an account
Login with your new credentials
Explore the dashboard

Sample Application

Build a CRM System

Follow this guide to build a complete Customer Relationship Management system with contacts, products, and invoices using HonoX

What You'll Build

👥

Contacts

Manage customer records with email, phone, company, and notes

📦

Products

Product catalog with pricing, SKU, and stock tracking

💰

Invoices

Full invoicing system with line items and status tracking

Generate CRM Project

Create a new project with database support

bunx @noundryfx/ndts-cli init
# Project name: crm-system
# Database: SQLite (or PostgreSQL for production)
# Auth: Custom JWT
# Email: None (for simplicity)
# Caching: Yes
# Other features: As needed

Define Database Schema

Add CRM tables to your schema

Edit packages/server/src/schema/schema.ts:

packages/server/src/schema/schema.ts

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';

// Contacts table
export const contacts = sqliteTable('contacts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  userId: integer('user_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
  name: text('name').notNull(),
  email: text('email'),
  phone: text('phone'),
  company: text('company'),
  address: text('address'),
  notes: text('notes'),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .$defaultFn(() => new Date())
});

// Products table
export const products = sqliteTable('products', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  userId: integer('user_id').notNull().references(() => users.id),
  name: text('name').notNull(),
  description: text('description'),
  price: integer('price').notNull(), // in cents
  sku: text('sku'),
  stock: integer('stock').default(0)
});

// Invoices table
export const invoices = sqliteTable('invoices', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  userId: integer('user_id').notNull().references(() => users.id),
  contactId: integer('contact_id').references(() => contacts.id),
  invoiceNumber: text('invoice_number').notNull(),
  status: text('status').notNull().default('draft'), // draft, sent, paid, overdue
  subtotal: integer('subtotal').notNull(),
  tax: integer('tax').default(0),
  total: integer('total').notNull(),
  issueDate: integer('issue_date', { mode: 'timestamp' }),
  dueDate: integer('due_date', { mode: 'timestamp' })
});

Generate and Run Migrations

Create database tables from your schema

cd crm-system
bun run db:generate  # Generate migration files
bun run db:migrate   # Apply migrations to database

Create API Routes

Add CRUD endpoints for contacts, products, and invoices

Create packages/server/src/routes/contacts.ts:

packages/server/src/routes/contacts.ts

import { Hono } from 'hono';
import { auth } from '../middleware/auth';
import { db } from '../config/database';
import { contacts } from '../schema/schema';
import { eq, and } from 'drizzle-orm';

const app = new Hono();

// Protect all routes
app.use('*', auth);

// Get all contacts
app.get('/', async (c) => {
  const userId = c.get('userId');
  const results = await db.select()
    .from(contacts)
    .where(eq(contacts.userId, userId));
  return c.json(results);
});

// Create contact
app.post('/', async (c) => {
  const userId = c.get('userId');
  const data = await c.req.json();
  const [contact] = await db.insert(contacts)
    .values({ ...data, userId })
    .returning();
  return c.json(contact, 201);
});

export default app;

💡 Tip: Create similar routes for products.ts and invoices.ts

Create Frontend Routes

Build JSX routes with HonoX file-based routing

Create packages/client/app/routes/contacts/index.tsx:

packages/client/app/routes/contacts/index.tsx

export default function Contacts() {
  return (
    <div class="container mx-auto p-4">
      <h1 class="text-3xl font-bold mb-4">Contactsh1>
      <div id="contacts-list" class="card">div>
    div>
  )
}

💡 Tip: HonoX automatically creates the /contacts route from this file structure!

Start Building!

Run your CRM system and start customizing

bun run dev

✓ Features Included:

• User authentication
• Contact management
• Product catalog
• Invoice creation
• Type-safe API & database

🎯 Next Steps:

• Customize page layouts
• Add validation logic
• Implement search/filters
• Add export features
• Deploy to production

File-Based Routing

HonoX Routes with JSX

Create .tsx files and HonoX automatically generates routes

Automatic Route Generation

app/routes/index.tsx

→ /

app/routes/about.tsx

→ /about

app/routes/records/index.tsx

→ /records

app/routes/records/[id].tsx

→ /records/:id

Example Route Component

app/routes/products.tsx

export default function Products() {
  return (
    <div class="container mx-auto p-8">
      <h1 class="text-3xl font-bold">Productsh1>
      <div class="grid grid-cols-3 gap-4">
        {/* Product cards */}
      div>
    div>
  )
}

Quick Install

Prerequisites