veloxts

VeloxTS Development Assistant

I help you build type-safe full-stack applications with VeloxTS. Ask me about:

• Creating API endpoints (procedures)
• Generating code (velox make resource, namespace, procedure)
• REST route inference from naming conventions
• Authentication and guards
• Validation with Zod schemas
• Troubleshooting common errors

Quick Decision: Which Generator?

"I have multiple Prisma models and want schemas + procedures for all of them"

velox sync                      # RECOMMENDED - interactive, all models at once
velox sync --force              # Skip prompts, generate everything with defaults

Generates: Zod schemas + CRUD procedures + router registration for every model

"I want to add a single new entity"

velox make resource Post        # Creates everything from scratch
velox make namespace Order      # For existing Prisma models only

"I need a single endpoint"

velox make procedure health     # Quick single procedure

See GENERATORS.md for detailed guidance.

Procedure Naming = REST Routes

VeloxTS infers HTTP methods from procedure names:

Critical: Non-standard names (like fetchUsers) are treated as mutations!

See PROCEDURES.md for the complete API reference.

Common Tasks

Create a New Resource

# Full CRUD with pagination
velox make resource BlogPost --crud --paginated

# With soft delete
velox make resource Comment --soft-delete

# Interactive field definition
velox make resource Product -i

Add Authentication

import { authenticated, hasRole } from '@veloxts/auth';

// Require login
getProfile: procedure()
  .guard(authenticated)
  .query(({ ctx }) => ctx.user),

// Require admin role
deleteUser: procedure()
  .guard(hasRole('admin'))
  .input(z.object({ id: z.string().uuid() }))
  .mutation(async ({ ctx, input }) => {
    await ctx.db.user.delete({ where: { id: input.id } });
    return { success: true };
  }),

Add Pagination

import { paginationInputSchema } from '@veloxts/velox';

listPosts: procedure()
  .input(paginationInputSchema.optional())
  .output(z.object({
    data: z.array(PostSchema),
    meta: z.object({
      page: z.number(),
      limit: z.number(),
      total: z.number(),
      totalPages: z.number(),
    }),
  }))
  .query(async ({ input, ctx }) => {
    const page = input?.page ?? 1;
    const limit = input?.limit ?? 10;
    const skip = (page - 1) * limit;

    const [data, total] = await Promise.all([
      ctx.db.post.findMany({ skip, take: limit }),
      ctx.db.post.count(),
    ]);

    return {
      data,
      meta: { page, limit, total, totalPages: Math.ceil(total / limit) },
    };
  }),

Custom REST Route

// Override automatic inference
publishPost: procedure()
  .input(z.object({ id: z.string().uuid() }))
  .output(PostSchema)
  .rest({ method: 'POST', path: '/posts/:id/publish' })  // No /api prefix!
  .mutation(async ({ ctx, input }) => {
    return ctx.db.post.update({
      where: { id: input.id },
      data: { publishedAt: new Date() },
    });
  }),

Troubleshooting

"useQuery is not a function"

Your procedure name doesn't follow query conventions:

// BAD - "fetchUsers" is not a query prefix
const { data } = api.users.fetchUsers.useQuery({});

// GOOD - "listUsers" is a query prefix
const { data } = api.users.listUsers.useQuery({});

"procedure.input is not a function"

Missing parentheses after procedure:

// BAD
getUser: procedure.input(...)

// GOOD
getUser: procedure().input(...)

Prisma Decimal validation fails

Use transforms for decimal fields:

// Input
price: z.coerce.number().positive()

// Output
price: z.any().transform((val) => Number(val))

See TROUBLESHOOTING.md for more solutions.

Project Structure

apps/
├── api/                    # Backend
│   ├── src/
│   │   ├── procedures/     # API endpoints (velox make procedure)
│   │   ├── schemas/        # Zod validation (velox make schema)
│   │   └── config/         # App configuration
│   └── prisma/
│       └── schema.prisma   # Database schema
│
└── web/                    # Frontend
    └── src/
        ├── routes/         # Pages
        └── components/     # UI components

CLI Quick Reference

# Development
pnpm dev                    # Start API (3030) + Web (8080) with HMR
pnpm velox dev --verbose    # API only with timing metrics

# Database
pnpm db:push                # Apply schema changes
pnpm db:studio              # Open Prisma Studio
pnpm velox migrate status   # Check migration status

# Code Generation
pnpm velox sync                           # All models at once (recommended)
pnpm velox make resource Post --crud      # Full resource (single model)
pnpm velox make namespace Order           # Existing model (single)
pnpm velox make procedure health          # Single procedure

# Seeding
pnpm velox db seed                        # Run all seeders
pnpm velox db seed --fresh                # Truncate + seed

Detailed Guides

• GENERATORS.md - Complete generator reference with decision tree
• PROCEDURES.md - Procedure API, guards, context, validation
• TROUBLESHOOTING.md - Error messages and fixes