Technology Stack

​

Core technologies

​

Runtime

​

Bun

• Fast: 3-4x faster than Node.js for common operations
• Native TypeScript: Run .ts files directly without transpilation
• Built-in tools: Package manager, bundler, test runner all included
• Web-standard APIs: Uses fetch, WebSocket, and other modern APIs
• Drop-in Node.js replacement: Runs existing Node.js code

• Runtime for all applications
• Package manager (bun install)
• Bundler for production builds
• Task runner for development

bun install

​

Frontend

​

Next.js

• App Router: File-system based routing with layouts
• React Server Components: Server-side rendering by default
• Server Actions: Type-safe mutations without API routes
• Streaming: Progressive rendering for better UX
• Image Optimization: Automatic image optimization and lazy loading

export default {
  reactCompiler: true, // React 19 optimizing compiler
};

​

React

• React Compiler (automatic memoization)
• Improved Suspense
• Server Components
• Server Actions

​

UI libraries

​

Backend

​

Hono

• Fast: One of the fastest Node.js frameworks
• Lightweight: Minimal overhead
• Edge-ready: Runs on Cloudflare Workers, Deno, Bun
• Type-safe: Full TypeScript support
• Middleware ecosystem: Rich plugin system

import { Hono } from "hono";
import { cors } from "hono/cors";
import { trpcServer } from "@hono/trpc-server";

const app = new Hono();

app.use("/api/*", cors({ 
  origin: env.CORS_ORIGIN,
  credentials: true 
}));

app.use("/trpc/*", trpcServer({ router: appRouter }));

export default app;

​

tRPC

• End-to-end type safety: Types flow from server to client
• No codegen: Types derived directly from router
• Simple: Just TypeScript functions
• Framework agnostic: Works with Next.js, React, CLI

import { router, protectedProcedure } from "./trpc";
import { z } from "zod";

export const appRouter = router({
  skill: {
    list: protectedProcedure.query(({ ctx }) => {
      return ctx.db.query.skills.findMany();
    }),
    
    create: protectedProcedure
      .input(z.object({ title: z.string(), content: z.string() }))
      .mutation(({ ctx, input }) => {
        return ctx.db.insert(skills).values(input);
      }),
  },
});

export type AppRouter = typeof appRouter;

import { createTRPCClient } from "@trpc/client";
import type { AppRouter } from "@better-skills/api";

const client = createTRPCClient<AppRouter>({
  url: "http://localhost:3000/trpc",
});

// Fully typed!
const skills = await client.skill.list.query();

​

Database

​

PostgreSQL

• Reliable: Battle-tested for decades
• Feature-rich: JSON, full-text search, geospatial
• ACID compliant: Strong consistency guarantees
• Extensible: Rich ecosystem of extensions

• Development: Local PostgreSQL 17
• Production: Neon (serverless PostgreSQL with connection pooling)

​

Drizzle ORM

• TypeScript-first: Schema defined in TypeScript
• Lightweight: Minimal runtime overhead
• Type-safe queries: Full IntelliSense for queries
• SQL-like: Query builder resembles SQL
• Migrations: Built-in migration system

import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";

export const skills = pgTable("skills", {
  id: uuid("id").primaryKey().defaultRandom(),
  userId: uuid("user_id").notNull(),
  title: text("title").notNull(),
  content: text("content").notNull(),
  createdAt: timestamp("created_at").defaultNow(),
});

import { db } from "@better-skills/db";
import { skills } from "@better-skills/db/schema";
import { eq } from "drizzle-orm";

// Fully typed!
const userSkills = await db
  .select()
  .from(skills)
  .where(eq(skills.userId, userId));

​

Neon

• Serverless: Scales to zero
• Connection pooling: PgBouncer built-in
• Branching: Database branches for development
• Backups: Automated point-in-time recovery

​

Authentication

​

Better Auth

• Type-safe: Full TypeScript support
• Flexible: Supports multiple providers
• Database-agnostic: Works with any database via adapters
• Secure: Built-in CSRF protection

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg" }),
  socialProviders: {
    google: {
      clientId: env.GOOGLE_CLIENT_ID,
      clientSecret: env.GOOGLE_CLIENT_SECRET,
    },
    github: {
      clientId: env.GITHUB_CLIENT_ID,
      clientSecret: env.GITHUB_CLIENT_SECRET,
    },
  },
});

• Google OAuth
• GitHub OAuth

​

CLI

​

@clack/prompts

• Beautiful, accessible prompts
• Keyboard navigation
• Multi-select, text input, confirm
• Loading spinners
• Color output

import * as p from "@clack/prompts";

p.intro("Better Skills CLI");

const skill = await p.text({
  message: "Skill name?",
  placeholder: "My skill",
});

const spinner = p.spinner();
spinner.start("Creating skill...");

await trpc.skill.create.mutate({ title: skill });

spinner.stop("Skill created!");
p.outro("Done!");

​

Build tools

​

Turborepo

• Intelligent caching: Never rebuild unchanged packages
• Parallel execution: Run tasks in parallel when possible
• Dependency awareness: Respects package dependencies
• Remote caching: Share cache across team (optional)

• Instant rebuilds when nothing changed
• Fast CI/CD pipelines
• Consistent builds across environments

​

Oxlint & Oxfmt

• Fast: 50-100x faster than ESLint/Prettier
• No config needed: Sensible defaults
• Rust-powered: Built in Rust for performance

bun run check  # Runs oxlint && oxfmt --write

​

tsdown

cd apps/server
bun run build  # Uses tsdown to create dist/index.mjs

​

Development tools

​

TypeScript

{
  "compilerOptions": {
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx"
  }
}

​

Husky

• pre-commit: Runs oxlint and oxfmt on staged files

bun run prepare  # Initializes Husky

​

lint-staged

{
  "lint-staged": {
    "*": "oxlint",
    "*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}": "oxfmt --write"
  }
}

​

Validation

​

Zod

• Environment variable validation
• tRPC input validation
• Form validation
• API response validation

import { z } from "zod";

const skillSchema = z.object({
  title: z.string().min(1).max(100),
  content: z.string().min(10),
});

// Throws if invalid
const skill = skillSchema.parse(input);

​

Markdown processing

​

gray-matter

import matter from "gray-matter";

const { data, content } = matter(markdownString);
// data = { title: "...", description: "..." }
// content = "# Heading\n\nContent..."

​

Version management

1. Catalog (root package.json) - Shared versions
2. Package-specific - Unique dependencies

bun update

​

Tech stack summary

​

Philosophy

​

Next steps