AI is taking over the world. Ideas that once were nothing but imagination floating in the air can now be turned into actual products that anyone around the world can use with a simple thought. If you had the chance—the opportunity—wouldn't you want to create the next billion-dollar product without having to spend thousands of dollars hiring engineers? Well, if that's your dream, let me take you down a little rabbit hole I stumbled into while trying to automate markdown to PDF.

FYI, this hook was written with speech-to-text using Wispr Flow.

Where it all began - The problem🤔

Earlier tonight, I was chaining a couple of prompts using NotebookLM and Claude. To make a long story short, the output I wanted was in markdown that I would parse into a Doc for a final PDF file. The flow was going well until I noticed that Claude wasn't delivering the result I needed. At that exact moment, I decided to test ChatGPT and Gemini—both failed.

Alternatively, I found a web app that did exactly what I needed, until I had to modify my text, which triggered a paywall. Not good! I didn't like that one bit, and I was too tired after a long week of work to dive into a research rabbit hole. Furthermore, I was bored. Thus, an idea popped into my head—Eureka! Let's just build the solution.

Time constraint

It's 7 PM Friday night, the kids have too much energy, and the holiday vacation has begun. Should I do this from scratch? Yes, maybe—but wait! That's when I remembered: vibe coding was a "thing," and although I see that feature literally every day, I'd never attempted it even once. The opportunity presented itself, and I had to seize it! And I did!

The Plan

I know how this goes—I've seen it before. First, you must start with a plan. So I toggled the agent panel and gave it some basic instructions, starting with a short markdown file:

# Project objective

user types in markdown compatible text field and it shows formatted preview on the right half of the screen.
The formatted preview can be converted to pdf and downloaded.

# infrastructure

- Monorepo

# frontend
- Nextjs 16
- Tailwindcss
- Shadcn

# backend
- trpcs
- supabase

From there, I started guiding it to build a plan for the solution: adding packages, system design, UI components, state management, auth, ORM, tRPC! That resulted in:

Full Project Plan

Project objective

user types in markdown compatible text field and it shows formatted preview on the right half of the screen.
The formatted preview can be converted to pdf and downloaded.

infrastructure

Turbo repo
monorepo
Bun (package manager and runtime)

Frontend

NextJs 16
TailwindCSS
Google Fonts (Google Sans, Google Sans Flex)
Zustand - State management (docs)
ShadCN
Craft Design System - Layout components and prose handling (docs, GitHub)
@react-pdf/renderer

Backend

tRPC
Drizzle
Supabase
Supabase Auth - User authentication

Environment Management

@t3-oss/env-nextjs - Type-safe environment variables with Zod validation

Architecture Principles

Organize by Features - Each entity has its own feature folder with components, hooks, server, client, types, constants, utils
Single Responsibility - Components render 1 thing, hooks do 1 thing, utilities do 1 thing
Component Hierarchy - Page components → Feature components → UI components
Fetch at Navigation Layer - Fetch in server components/loaders, pass data down (or through React Query)
Shared Feature Folder - features/shared for shared UI components, hooks, types, server functions
Lib Folder - Low-level utilities (database, env, 3rd party clients) outside features

Monorepo Structuremd-to-pdf/
├── apps/
│ └── web/ # Next.js 16 application
│ ├── app/ # Next.js app router (page components)
│ │ ├── page.tsx # Main editor page
│ │ ├── documents/
│ │ │ └── [id]/
│ │ │ └── page.tsx # Document detail page
│ │ └── layout.tsx # Root layout
│ ├── features/ # Feature-based organization
│ │ ├── editor/ # Markdown editor feature
│ │ │ ├── components/ # Feature components
│ │ │ │ └── Editor.tsx
│ │ │ ├── hooks/ # Feature hooks
│ │ │ │ └── useEditor.ts
│ │ │ ├── server/ # Server functions (tRPC procedures)
│ │ │ │ └── editor.ts
│ │ │ ├── client/ # Client-side utilities
│ │ │ │ └── editor-client.ts
│ │ │ ├── types.ts # Feature types
│ │ │ ├── constants.ts # Feature constants
│ │ │ └── utils.ts # Feature utilities
│ │ ├── preview/ # Preview pane feature
│ │ │ ├── components/
│ │ │ │ └── Preview.tsx
│ │ │ ├── hooks/
│ │ │ │ └── usePreview.ts
│ │ │ ├── server/
│ │ │ ├── client/
│ │ │ ├── types.ts
│ │ │ ├── constants.ts
│ │ │ └── utils.ts
│ │ ├── pdf-export/ # PDF export feature
│ │ │ ├── components/
│ │ │ │ └── PDFExporter.tsx
│ │ │ ├── hooks/
│ │ │ │ └── usePDFExport.ts
│ │ │ ├── server/
│ │ │ ├── client/
│ │ │ │ └── pdf-generator.ts
│ │ │ ├── types.ts
│ │ │ ├── constants.ts
│ │ │ └── utils.ts
│ │ ├── document/ # Document persistence feature
│ │ │ ├── components/
│ │ │ │ ├── DocumentList.tsx
│ │ │ │ └── DocumentSave.tsx
│ │ │ ├── hooks/
│ │ │ │ └── useDocument.ts
│ │ │ ├── server/
│ │ │ │ └── document.ts # tRPC procedures
│ │ │ ├── client/
│ │ │ ├── types.ts
│ │ │ ├── constants.ts
│ │ │ └── utils.ts
│ │ ├── auth/ # Authentication feature
│ │ │ ├── components/
│ │ │ │ ├── LoginForm.tsx
│ │ │ │ ├── SignUpForm.tsx
│ │ │ │ └── UserMenu.tsx
│ │ │ ├── hooks/
│ │ │ │ ├── useAuth.ts
│ │ │ │ └── useSession.ts
│ │ │ ├── server/
│ │ │ │ └── auth.ts # Auth server utilities
│ │ │ ├── client/
│ │ │ │ └── auth-client.ts # Supabase auth client
│ │ │ ├── types.ts
│ │ │ ├── constants.ts
│ │ │ └── utils.ts
│ │ └── shared/ # Shared UI feature
│ │ ├── components/ # Shared UI components (ShadCN + Craft DS)
│ │ │ ├── ds/ # Craft Design System components
│ │ │ │ ├── Layout.tsx
│ │ │ │ ├── Main.tsx
│ │ │ │ ├── Section.tsx
│ │ │ │ ├── Container.tsx
│ │ │ │ ├── Nav.tsx
│ │ │ │ └── Prose.tsx
│ │ │ ├── Button.tsx # ShadCN components
│ │ │ ├── Input.tsx
│ │ │ └── ...
│ │ ├── hooks/
│ │ │ └── useDebounce.ts
│ │ ├── server/
│ │ ├── client/
│ │ ├── types.ts
│ │ ├── constants.ts
│ │ └── utils.ts
│ ├── lib/ # Low-level utilities (non-UI)
│ │ ├── db/ # Database client & schema
│ │ │ ├── client.ts # Drizzle client
│ │ │ └── schema.ts # Drizzle schema
│ │ ├── env/ # Environment variables
│ │ │ └── env.ts
│ │ ├── trpc/ # tRPC setup
│ │ │ ├── client.ts # tRPC client
│ │ │ └── server.ts # tRPC server setup
│ │ ├── stores/ # Zustand stores
│ │ │ ├── editor-store.ts # Editor state store
│ │ │ ├── auth-store.ts # Auth state store
│ │ │ └── ui-store.ts # UI state store
│ │ └── supabase/ # Supabase client
│ │ └── client.ts
│ └── styles/ # Global styles
│ └── globals.css
├── packages/
│ ├── api/ # tRPC router & procedures
│ │ ├── src/
│ │ │ ├── router/ # tRPC routers (imports from features)
│ │ │ │ └── index.ts # Root router
│ │ │ └── trpc.ts # tRPC initialization
│ │ └── package.json
│ ├── config/ # Shared configs
│ │ ├── eslint/
│ │ ├── typescript/
│ │ └── tailwind/
│ └── types/ # Shared TypeScript types
├── turbo.json
└── package.json
Component Hierarchy & Data FlowComponent Layers

Page Components (app/*/page.tsx)
- Entry points for routes
- Server components (fetch data)
- Render feature components
- Pass data down (or through React Query)
Feature Components (features/*/components/*.tsx)
- Domain-specific components
- Single responsibility
- Use UI components from features/shared
- Use feature hooks
UI Components (features/shared/components/*.tsx)
- Reusable, presentational components
- Single responsibility
- No business logic
- ShadCN components live here

Data Flow Exampleapp/page.tsx (Server Component)
↓ fetches data
↓ passes to feature components
features/editor/components/Editor.tsx
↓ uses hook
features/editor/hooks/useEditor.ts
↓ uses client utility
features/editor/client/editor-client.ts
Fetching Strategy

Server Components: Fetch in app/*/page.tsx using server functions
Client Components: Use React Query with tRPC for mutations/refetches
Never: Fetch in UI components or feature components directly
Always: Pass data as props or use React Query context

Feature BreakdownFeature: editor

Responsibility: Markdown text input and editing

Components

Editor.tsx - Single responsibility: renders markdown textarea

Hooks

useEditor.ts - Single responsibility: manages editor state (content, cursor position)

Server

None (client-side only)

Client

editor-client.ts - Utilities for editor operations (syntax highlighting, etc.)

Types

EditorState, EditorConfig

Constants

Default editor settings, key bindings

Utils

Text manipulation utilities

Feature: preview

Responsibility: Live markdown preview rendering

Components

Preview.tsx - Single responsibility: renders markdown as HTML

Hooks

usePreview.ts - Single responsibility: converts markdown to HTML

Server

None (client-side only)

Client

preview-client.ts - Markdown parsing utilities

Types

PreviewConfig, PreviewOptions

Constants

Preview styling options

Utils

Markdown transformation utilities

Feature: pdf-export

Responsibility: PDF generation and download

Components

PDFExporter.tsx - Single responsibility: renders export button/controls

Hooks

usePDFExport.ts - Single responsibility: handles PDF generation and download

Server

None (client-side generation)

Client

pdf-generator.ts - Single responsibility: converts markdown/HTML to PDF using @react-pdf/renderer

Types

PDFOptions, PDFConfig

Constants

PDF styling constants, default options

Utils

PDF formatting utilities

Feature: document

Responsibility: Document persistence (save/load)

Components

DocumentList.tsx - Single responsibility: renders list of saved documents
DocumentSave.tsx - Single responsibility: renders save document form

Hooks

useDocument.ts - Single responsibility: manages document CRUD operations

Server

document.ts - tRPC procedures:
- create - Create document
- getById - Get document by ID
- update - Update document
- delete - Delete document
- list - List user documents

Client

document-client.ts - Client-side document utilities

Types

Document, DocumentInput, DocumentListResponse

Constants

Document validation rules

Utils

Document transformation utilities

Feature: auth

Responsibility: User authentication and session management

Components

LoginForm.tsx - Single responsibility: renders login form
SignUpForm.tsx - Single responsibility: renders sign up form
UserMenu.tsx - Single responsibility: renders user menu/dropdown

Hooks

useAuth.ts - Single responsibility: manages authentication state and actions (login, signup, logout)
useSession.ts - Single responsibility: manages current user session

Server

auth.ts - Server-side auth utilities (session validation, protected routes)

Client

auth-client.ts - Supabase auth client configuration and utilities

Types

User, Session, AuthState

Constants

Auth configuration constants

Utils

Auth validation and transformation utilities

Feature: shared

Responsibility: Shared UI components and utilities

Components

Craft Design System components (docs):
- Layout.tsx - Root layout component with base styling
- Main.tsx - Primary content area
- Section.tsx - Semantic section container with vertical padding
- Container.tsx - Centers content with max width and padding
- Nav.tsx - Navigation container
- Prose.tsx - Rich text content with comprehensive typography styling
ShadCN UI components (Button, Input, Card, etc.)
Each component has single responsibility

Hooks

useDebounce.ts - Single responsibility: debounce values
Other shared hooks as needed

Server

Shared server utilities if needed

Client

Shared client utilities

Types

Shared UI types

Constants

Shared UI constants (themes, breakpoints, etc.)

Utils

Shared UI utilities

Craft Design System Usage

Craft Design System provides layout components and prose handling. It's compatible with shadcn/ui and works seamlessly with Tailwind CSS.

Layout Setup

Location: apps/web/app/layout.tsx

import { Google_Sans, Google_Sans_Flex } from "next/font/google";
import { Layout } from "@/app/features/shared/components/ds/Layout";

const googleSans = Google_Sans({
subsets: ["latin"],
variable: "--font-google-sans",
display: "swap",
});

const googleSansFlex = Google_Sans_Flex({
subsets: ["latin"],
variable: "--font-google-sans-flex",
display: "swap",
});

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html
lang="en"
className={`${googleSans.variable} ${googleSansFlex.variable}`}
>
<Layout>{children}</Layout>
</html>
);
}
Component UsageMain Layout Structureimport { Main, Section, Container } from "@/app/features/shared/components/ds";

export default function Page() {
return (
<Main>
<Section>
<Container>{/* Page content */}</Container>
</Section>
</Main>
);
}
Navigationimport { Nav } from "@/app/features/shared/components/ds";

<Nav>
<div>Logo</div>
<ul>
<li>
<a href="/">Home</a>
</li>
<li>
<a href="/documents">Documents</a>
</li>
</ul>
</Nav>;
Prose Component (for Markdown Preview)

The Prose component is ideal for rendering markdown content with comprehensive typography styling:

import { Prose } from "@/app/features/shared/components/ds";

// In Preview feature component
<Prose isArticle={true} isSpaced={true}>
{/* Rendered markdown content */}
</Prose>;

Prose Features:

Comprehensive typography system (headings, paragraphs, lists, etc.)
Code block styling
Table styling
Blockquote styling
Link styling with hover states
Image and media support

Integration with FeaturesEditor Layout

Use Craft components for the split-view editor layout:

import { Main, Section, Container } from "@/app/features/shared/components/ds";

<Main>
<Section>
<Container className="grid grid-cols-2 gap-4">
<EditorFeature />
<PreviewFeature />
</Container>
</Section>
</Main>;
Document Pages

Use Prose for document content display:

import { Prose } from "@/app/features/shared/components/ds";

<Prose isArticle={true} isSpaced={true}>
<h1>{document.title}</h1>
{/* Document content */}
</Prose>;
Component Props

All Craft components accept:

className - Custom Tailwind classes
children - React children
id - HTML id attribute
style - Inline styles
containerClassName - For Nav component
isArticle - For Prose (renders as <article>)
isSpaced - For Prose (adds vertical spacing)

Page Components/ (Main Editor Page)

File: app/page.tsx

Responsibility: Entry point for editor, fetches initial data

// Server component - fetches data at navigation layer
export default async function EditorPage() {
// Fetch initial data if needed (e.g., recent documents)
const recentDocs = await getRecentDocuments();

return (
<EditorLayout>
<EditorFeature />
<PreviewFeature />
<PDFExportFeature />
</EditorLayout>
);
}
/documents/[id] (Document Detail Page)

File: app/documents/[id]/page.tsx

Responsibility: Loads and displays saved document

// Server component - fetches document data
export default async function DocumentPage({ params }) {
const document = await getDocumentById(params.id);

return (
<DocumentLayout>
<DocumentFeature document={document} />
<EditorFeature initialContent={document.content} />
<PreviewFeature />
</DocumentLayout>
);
}
Database Setup (Drizzle + Supabase)Schema Definition

Location: apps/web/lib/db/schema.ts

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

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

export type Document = typeof documents.$inferSelect;
export type NewDocument = typeof documents.$inferInsert;
Database Client

Location: apps/web/lib/db/client.ts

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import * as schema from "@/app/lib/db/schema";
import { env } from "@/app/lib/env/env";

// Disable prefetch as it is not supported for "Transaction" pool mode
const client = postgres(env.DATABASE_URL, { prepare: false });
export const db = drizzle(client, { schema });
Drizzle Configuration

Location: apps/web/drizzle.config.ts

import type { Config } from "drizzle-kit";
import { env } from "./lib/env/env";

export default {
schema: "./lib/db/schema.ts",
out: "./drizzle",
dialect: "postgresql",
dbCredentials: {
url: env.DATABASE_URL,
},
} satisfies Config;
Environment Variables Setup

Location: apps/web/lib/env/env.ts

Using @t3-oss/env-nextjs for type-safe environment variable validation:

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
server: {
DATABASE_URL: z.string().url(),
SUPABASE_URL: z.string().url(),
SUPABASE_ANON_KEY: z.string().min(1),
SUPABASE_SERVICE_ROLE_KEY: z.string().min(1).optional(), // For server-side operations
},
client: {
NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
},
// For Next.js >= 13.4.4, you only need to destructure client variables:
experimental__runtimeEnv: {
NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
NEXT_PUBLIC_SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
},
// For Next.js < 13.4.4, specify runtimeEnv manually:
runtimeEnv: {
DATABASE_URL: process.env.DATABASE_URL,
SUPABASE_URL: process.env.SUPABASE_URL,
SUPABASE_ANON_KEY: process.env.SUPABASE_ANON_KEY,
SUPABASE_SERVICE_ROLE_KEY: process.env.SUPABASE_SERVICE_ROLE_KEY,
NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
NEXT_PUBLIC_SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
},
});

Location: apps/web/.env.local

DATABASE_URL="postgresql://user:password@host:port/database"
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key" # Optional, for server-side operations

# Client-side variables (must be prefixed with NEXT_PUBLIC_)
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"

Important: Import the env file in next.config.ts to validate environment variables at build time (see Next.js Configuration section).

Migration Commands# Generate migration
bunx drizzle-kit generate

# Run migration
bunx drizzle-kit push

# View migrations
bunx drizzle-kit studio
Supabase Auth SetupClient Configuration

Location: apps/web/lib/supabase/client.ts

import { createBrowserClient } from "@supabase/ssr";
import { env } from "@/app/lib/env/env";

export const createClient = () => {
return createBrowserClient(
env.NEXT_PUBLIC_SUPABASE_URL,
env.NEXT_PUBLIC_SUPABASE_ANON_KEY
);
};
Server Client Configuration

Location: apps/web/lib/supabase/server.ts

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import { env } from "@/app/lib/env/env";

export const createClient = async () => {
const cookieStore = await cookies();

return createServerClient(
env.NEXT_PUBLIC_SUPABASE_URL,
env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
{
cookies: {
getAll() {
return cookieStore.getAll();
},
setAll(cookiesToSet) {
try {
cookiesToSet.forEach(({ name, value, options }) => {
cookieStore.set(name, value, options);
});
} catch (error) {
// The `setAll` method was called from a Server Component.
// This can be ignored if you have middleware refreshing
// user sessions.
}
},
},
}
);
};
Middleware for Session Refresh

Location: apps/web/middleware.ts

import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";
import { env } from "@/app/lib/env/env";

export async function middleware(request: NextRequest) {
let response = NextResponse.next({
request: {
headers: request.headers,
},
});

const supabase = createServerClient(
env.NEXT_PUBLIC_SUPABASE_URL,
env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
{
cookies: {
getAll() {
return request.cookies.getAll();
},
setAll(cookiesToSet) {
cookiesToSet.forEach(({ name, value, options }) => {
request.cookies.set(name, value);
});
response = NextResponse.next({
request,
});
cookiesToSet.forEach(({ name, value, options }) => {
response.cookies.set(name, value, options);
});
},
},
}
);

await supabase.auth.getUser();

return response;
}

export const config = {
matcher: [
/*
* Match all request paths except for the ones starting with:
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico (favicon file)
* Feel free to modify this pattern to include more paths.
*/
"/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
],
};
Auth Feature Client

Location: apps/web/features/auth/client/auth-client.ts

import { createClient } from "@/app/lib/supabase/client";

export const supabase = createClient();

// Auth helper functions
export const signIn = async (email: string, password: string) => {
const { data, error } = await supabase.auth.signInWithPassword({
email,
password,
});
return { data, error };
};

export const signUp = async (email: string, password: string) => {
const { data, error } = await supabase.auth.signUp({
email,
password,
});
return { data, error };
};

export const signOut = async () => {
const { error } = await supabase.auth.signOut();
return { error };
};

export const getSession = async () => {
const {
data: { session },
error,
} = await supabase.auth.getSession();
return { session, error };
};

export const getUser = async () => {
const {
data: { user },
error,
} = await supabase.auth.getUser();
return { user, error };
};
Auth Hook

Location: apps/web/features/auth/hooks/useAuth.ts

"use client";

import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import type { User, Session } from "@supabase/supabase-js";
import {
getSession,
signIn,
signUp,
signOut,
} from "@/app/features/auth/client/auth-client";

export function useAuth() {
const [user, setUser] = useState<User | null>(null);
const [session, setSession] = useState<Session | null>(null);
const [loading, setLoading] = useState(true);
const router = useRouter();

useEffect(() => {
getSession().then(({ session, error }) => {
if (error) {
console.error("Error getting session:", error);
setLoading(false);
return;
}
setSession(session);
setUser(session?.user ?? null);
setLoading(false);
});
}, []);

const handleSignIn = async (email: string, password: string) => {
const { data, error } = await signIn(email, password);
if (error) {
return { error };
}
if (data.session) {
setSession(data.session);
setUser(data.session.user);
router.refresh();
}
return { data, error };
};

const handleSignUp = async (email: string, password: string) => {
const { data, error } = await signUp(email, password);
if (error) {
return { error };
}
if (data.session) {
setSession(data.session);
setUser(data.session.user);
router.refresh();
}
return { data, error };
};

const handleSignOut = async () => {
const { error } = await signOut();
if (error) {
return { error };
}
setSession(null);
setUser(null);
router.refresh();
return { error };
};

return {
user,
session,
loading,
signIn: handleSignIn,
signUp: handleSignUp,
signOut: handleSignOut,
};
}
tRPC SetupRouter Structure

Location: packages/api/src/router/index.ts

import { router } from "@trpc/server";
import { documentRouter } from "@/app/features/document/server/document";

export const appRouter = router({
document: documentRouter,
});

export type AppRouter = typeof appRouter;

Each feature's server folder contains its tRPC procedures, which are imported into the root router.

Server Setup

Location: apps/web/lib/trpc/server.ts

import { initTRPC } from "@trpc/server";
import { db } from "@/app/lib/db/client";

const t = initTRPC.context<{ db: typeof db }>().create();

export const router = t.router;
export const publicProcedure = t.procedure;
Client Setup

Location: apps/web/lib/trpc/client.ts

import { createTRPCReact } from "@trpc/react-query";
import type { AppRouter } from "@/packages/api/src/router";

export const trpc = createTRPCReact<AppRouter>();
Next.js App Router Integration

Location: apps/web/app/api/trpc/[trpc]/route.ts

import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@/packages/api/src/router";
import { db } from "@/app/lib/db/client";

const handler = (req: Request) =>
fetchRequestHandler({
endpoint: "/api/trpc",
req,
router: appRouter,
createContext: () => ({ db }),
});

export { handler as GET, handler as POST };
React Query Provider

Location: apps/web/app/providers.tsx

"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { httpBatchLink } from "@trpc/client";
import { useState } from "react";
import { trpc } from "@/app/lib/trpc/client";

export function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(() => new QueryClient());
const [trpcClient] = useState(() =>
trpc.createClient({
links: [
httpBatchLink({
url: "/api/trpc",
}),
],
})
);

return (
<trpc.Provider client={trpcClient} queryClient={queryClient}>
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
</trpc.Provider>
);
}

Location: apps/web/app/layout.tsx

import { Google_Sans, Google_Sans_Flex } from "next/font/google";
import { Providers } from "@/app/providers";

const googleSans = Google_Sans({
subsets: ["latin"],
variable: "--font-google-sans",
display: "swap",
});

const googleSansFlex = Google_Sans_Flex({
subsets: ["latin"],
variable: "--font-google-sans-flex",
display: "swap",
});

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html
lang="en"
className={`${googleSans.variable} ${googleSansFlex.variable}`}
>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Google Fonts ConfigurationFont Setup

The project uses Google Sans and Google Sans Flex fonts from Google Fonts, integrated with Next.js and TailwindCSS.

Installation

Google Fonts are loaded via Next.js's built-in next/font/google optimization.

Font Configuration

Location: apps/web/app/layout.tsx

import { Google_Sans, Google_Sans_Flex } from "next/font/google";
import { Providers } from "@/app/providers";

const googleSans = Google_Sans({
subsets: ["latin"],
variable: "--font-google-sans",
display: "swap",
});

const googleSansFlex = Google_Sans_Flex({
subsets: ["latin"],
variable: "--font-google-sans-flex",
display: "swap",
});

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html
lang="en"
className={`${googleSans.variable} ${googleSansFlex.variable}`}
>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
TailwindCSS Configuration

Location: apps/web/tailwind.config.ts

import type { Config } from "tailwindcss";

const config: Config = {
theme: {
extend: {
fontFamily: {
sans: ["var(--font-google-sans)", "sans-serif"],
"sans-flex": ["var(--font-google-sans-flex)", "sans-serif"],
},
},
},
// ... rest of your Tailwind config
};

export default config;
UsageIn Components// Using Google Sans (default sans font)
<div className="font-sans">Text with Google Sans</div>

// Using Google Sans Flex
<div className="font-sans-flex">Text with Google Sans Flex</div>
In Craft Design System Components

Craft components will automatically use the configured fonts through TailwindCSS:

import { Prose, Container } from "@/app/features/shared/components/ds";

<Container className="font-sans">
<Prose>
<h1>Heading with Google Sans</h1>
<p>Body text with Google Sans</p>
</Prose>
</Container>;
Custom Font Usage// Mix fonts as needed
<div className="font-sans text-2xl">Google Sans Heading</div>
<div className="font-sans-flex text-base">Google Sans Flex Body</div>
Font Variables

The fonts are available as CSS variables:

--font-google-sans - Google Sans font family
--font-google-sans-flex - Google Sans Flex font family

These can be used directly in CSS or with Tailwind's font-sans and font-sans-flex utilities.

Zustand State Management

Zustand is a small, fast, and scalable state management solution with a comfy API based on hooks. It's lightweight and perfect for managing global application state.

Store Structure

Stores are located in apps/web/lib/stores/ and follow the single responsibility principle.

Editor Store

Location: apps/web/lib/stores/editor-store.ts

import { create } from "zustand";

interface EditorState {
content: string;
cursorPosition: number;
setContent: (content: string) => void;
setCursorPosition: (position: number) => void;
reset: () => void;
}

export const useEditorStore = create<EditorState>((set) => ({
content: "",
cursorPosition: 0,
setContent: (content) => set({ content }),
setCursorPosition: (position) => set({ cursorPosition: position }),
reset: () => set({ content: "", cursorPosition: 0 }),
}));
Auth Store

Location: apps/web/lib/stores/auth-store.ts

import { create } from "zustand";
import type { User, Session } from "@supabase/supabase-js";

interface AuthState {
user: User | null;
session: Session | null;
loading: boolean;
setUser: (user: User | null) => void;
setSession: (session: Session | null) => void;
setLoading: (loading: boolean) => void;
clear: () => void;
}

export const useAuthStore = create<AuthState>((set) => ({
user: null,
session: null,
loading: true,
setUser: (user) => set({ user }),
setSession: (session) => set({ session }),
setLoading: (loading) => set({ loading }),
clear: () => set({ user: null, session: null, loading: false }),
}));
UI Store

Location: apps/web/lib/stores/ui-store.ts

import { create } from "zustand";

interface UIState {
sidebarOpen: boolean;
theme: "light" | "dark";
toggleSidebar: () => void;
setTheme: (theme: "light" | "dark") => void;
}

export const useUIStore = create<UIState>((set) => ({
sidebarOpen: false,
theme: "light",
toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
setTheme: (theme) => set({ theme }),
}));
Usage in ComponentsSelecting State"use client";

import { useEditorStore } from "@/app/lib/stores/editor-store";

export function Editor() {
// Select only the state you need - component re-renders only when this changes
const content = useEditorStore((state) => state.content);
const setContent = useEditorStore((state) => state.setContent);

return (
<textarea value={content} onChange={(e) => setContent(e.target.value)} />
);
}
Using Multiple Stores"use client";

import { useEditorStore } from "@/app/lib/stores/editor-store";
import { useAuthStore } from "@/app/lib/stores/auth-store";

export function EditorWithAuth() {
const content = useEditorStore((state) => state.content);
const user = useAuthStore((state) => state.user);
const setContent = useEditorStore((state) => state.setContent);

if (!user) {
return <div>Please log in</div>;
}

return (
<textarea value={content} onChange={(e) => setContent(e.target.value)} />
);
}
Using Actions"use client";

import { useEditorStore } from "@/app/lib/stores/editor-store";

export function EditorControls() {
const reset = useEditorStore((state) => state.reset);
const setCursorPosition = useEditorStore((state) => state.setCursorPosition);

return (
<div>
<button onClick={reset}>Reset</button>
<button onClick={() => setCursorPosition(0)}>Go to Start</button>
</div>
);
}
Integration with FeaturesEditor Feature

The editor feature can use the Zustand store instead of local state:

"use client";

import { useEditorStore } from "@/app/lib/stores/editor-store";
import { useEffect } from "react";

export function Editor() {
const { content, setContent, setCursorPosition } = useEditorStore();

// Sync with external changes if needed
useEffect(() => {
// Any side effects based on store changes
}, [content]);

return (
<textarea
value={content}
onChange={(e) => {
setContent(e.target.value);
setCursorPosition(e.target.selectionStart);
}}
/>
);
}
Auth Feature

The auth feature can integrate with the Zustand store:

"use client";

import { useAuthStore } from "@/app/lib/stores/auth-store";
import { useEffect } from "react";
import { getSession } from "@/app/features/auth/client/auth-client";

export function AuthProvider({ children }: { children: React.ReactNode }) {
const { setUser, setSession, setLoading } = useAuthStore();

useEffect(() => {
getSession().then(({ session, error }) => {
if (error) {
setLoading(false);
return;
}
setSession(session);
setUser(session?.user ?? null);
setLoading(false);
});
}, [setUser, setSession, setLoading]);

return <>{children}</>;
}
Best Practices

Single Responsibility: Each store should manage one domain of state
Selective Subscriptions: Always select only the state you need to avoid unnecessary re-renders
Actions in Store: Keep actions (functions that modify state) in the store definition
Type Safety: Use TypeScript interfaces for store state
No Providers Needed: Zustand stores work without providers - use them anywhere

TypeScript ConfigurationTypeScript SetupRequirements

TypeScript: Latest version (minimum 5.1.3 required for async Server Components, latest is 5.6+)
@types/react: Latest version (minimum 18.2.8 required, latest is 19.x)
Node.js: v22.10.0 or higher (for native TypeScript resolver in next.config.ts)

Note: Always use the latest stable versions. Check package versions with bun outdated or visit npm registry pages.

Path Aliases

Location: apps/web/tsconfig.json and packages/api/tsconfig.json

TypeScript must be configured with the following path aliases:

{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/app/*": ["./apps/web/*"],
"@/packages/*": ["./packages/*"]
},
"incremental": true
}
}

Note: baseUrl is required for path aliases to work correctly. incremental enables faster type checking for larger applications.

Usage Examples// In apps/web
import { Button } from "@/app/features/shared/components/Button";
import { useEditor } from "@/app/features/editor/hooks/useEditor";
import { db } from "@/app/lib/db/client";

// In packages/api
import { documentRouter } from "@/app/features/document/server/document";
Next.js Configuration

Location: apps/web/next.config.ts (TypeScript format)

Next.js configuration must use TypeScript format (next.config.ts):

import type { NextConfig } from "next";
import path from "path";

// Import env here to validate during build time
// This ensures environment variables are validated at build time
import "./lib/env/env";

const nextConfig: NextConfig = {
// Enable statically typed routes for type-safe navigation
typedRoutes: true,

// Configure webpack to resolve path aliases
webpack: (config) => {
config.resolve.alias = {
...config.resolve.alias,
"@/app": path.resolve(__dirname, "."),
"@/packages": path.resolve(__dirname, "../packages"),
};
return config;
},

// TypeScript configuration
typescript: {
// Fail build on TypeScript errors (recommended)
ignoreBuildErrors: false,
},
};

export default nextConfig;

Important Notes:

Use next.config.ts (not .js or .mjs) for TypeScript support
typedRoutes: true enables compile-time type checking for route paths
For Node.js v22.10.0 - v22.17.x, you may need: NODE_OPTIONS=--experimental-transform-types
Node.js v22.18.0+ has native TypeScript resolver enabled by default

Turbo Repo Configuration

Location: Root tsconfig.json

For monorepo setups, configure TypeScript at the root level:

{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/app/*": ["./apps/web/*"],
"@/packages/*": ["./packages/*"]
}
},
"references": [{ "path": "./apps/web" }, { "path": "./packages/api" }]
}

Location: apps/web/tsconfig.json

Extend from root and add Next.js specific settings:

{
"extends": "../../tsconfig.json",
"compilerOptions": {
"target": "ES2020",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"incremental": true,
"plugins": [
{
"name": "next"
}
],
"paths": {
"@/app/*": ["./*"],
"@/packages/*": ["../../packages/*"]
}
},
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
"exclude": ["node_modules"]
}
Development WorkflowSetup Steps

Initialize Turbo repo
Create apps/web (Next.js 16 with TypeScript)
Create packages/api (tRPC)
Install dependencies using Bun (use @latest to get the most recent versions):
- bun add next@latest react@latest react-dom@latest @types/react@latest @types/react-dom@latest @types/node@latest @t3-oss/env-nextjs@latest zod@latest zustand@latest @tanstack/react-query@latest @trpc/client@latest @trpc/react-query@latest @trpc/next@latest @react-pdf/renderer@latest react-markdown@latest remark-gfm@latest tailwindcss@latest
- bun add -d typescript@latest turbo@latest
- bun add @trpc/server@latest drizzle-orm@latest @supabase/supabase-js@latest @supabase/ssr@latest drizzle-kit@latest postgres@latest
Configure TypeScript path aliases in root tsconfig.json (@/app, @/packages)
Configure app-specific tsconfig.json with Next.js settings
Set up environment variables:
- Create lib/env/env.ts with @t3-oss/env-nextjs schema
- Create .env.local with required variables
Create next.config.ts (TypeScript format) with:
- Import env file for build-time validation
- typedRoutes: true for type-safe navigation
- Path alias resolution
Set up feature folder structure
Configure lib folder (db, env, trpc, supabase)
Set up Supabase connection:
- Create Supabase client (lib/supabase/client.ts)
- Create Supabase server client (lib/supabase/server.ts)
- Create middleware for session refresh (middleware.ts)
Set up Supabase Auth:
- Configure auth feature folder structure
- Create auth client utilities (features/auth/client/auth-client.ts)
- Create auth hooks (features/auth/hooks/useAuth.ts)
- Create auth components (LoginForm, SignUpForm, UserMenu)
Configure Drizzle schema and migrations
Set up tRPC client/server
Configure TailwindCSS:
- Create tailwind.config.ts
- Configure Google Fonts in fontFamily extension
Configure Google Fonts:
- Import Google Sans and Google Sans Flex in app/layout.tsx
- Add font variables to HTML element
Initialize ShadCN in features/shared: bunx shadcn@latest init
Initialize Craft Design System: bunx craft-ds@latest init (requires shadcn/ui)

Bun CommandsPackage Management# Install dependencies
bun install

# Add a dependency
bun add <package>

# Add a dev dependency
bun add -d <package>

# Remove a dependency
bun remove <package>
Development# Run development server
bun dev

# Run build
bun build

# Run production server
bun start
Scripts# Run scripts defined in package.json
bun run <script-name>

# Run with bunx (similar to npx)
bunx <package>
Version Management# Check for outdated packages
bun outdated

# Update all dependencies to latest versions
bun update

# Update a specific package to latest
bun add <package>@latest

# Upgrade Bun itself
bun upgrade
Key Dependencies

Note: Package versions change frequently. Always check for the latest stable versions before installation. Use bun add <package>@latest to get the most recent version, or visit the package's npm page for version information.

System Requirements

Bun: Latest stable version (run bun upgrade to update)
Node.js: v22.10.0 or higher (v22.18.0+ recommended for native TypeScript resolver) - Optional if using Bun runtime

Root

turbo@latest - Monorepo build system
typescript@latest - TypeScript support (minimum 5.1.3 required for async Server Components, latest is 5.6+)
@types/node@latest - Node.js type definitions

Frontend (apps/web)

next@latest - Next.js framework (latest stable: 16.0.7+)
react@latest - React library (latest: 19.x)
react-dom@latest - React DOM (latest: 19.x)
@types/react@latest - React type definitions (latest: 19.x, minimum 18.2.8 required)
@types/react-dom@latest - React DOM type definitions (latest: 19.x)
@t3-oss/env-nextjs@latest - Type-safe environment variables (latest: 0.13.8+) (docs)
zod@latest - Schema validation for environment variables
zustand@latest - State management (docs)
@tanstack/react-query@latest - For tRPC client and data fetching (latest: 5.x)
@trpc/client@latest, @trpc/react-query@latest, @trpc/next@latest - tRPC client libraries (latest: 11.x)
@react-pdf/renderer@latest - PDF generation
react-markdown@latest - Markdown rendering
remark-gfm@latest - GitHub Flavored Markdown support
tailwindcss@latest - CSS framework
shadcn/ui - UI component library (install via CLI: bunx shadcn@latest init)
craft-ds@latest - Craft Design System for layouts and prose (install via CLI: bunx craft-ds@latest init) (docs, GitHub)

Backend (packages/api)

@trpc/server@latest - tRPC server (latest: 11.x)
drizzle-orm@latest - TypeScript ORM (latest: 1.5.0+)
@supabase/supabase-js@latest - Supabase client
@supabase/ssr@latest - Supabase SSR utilities for Next.js (required for auth)
drizzle-kit@latest - Drizzle migrations and tooling (latest: 0.28.0+)
postgres@latest or @neondatabase/serverless@latest - PostgreSQL driver (depending on Supabase setup)

Installation Command

To install all dependencies with latest versions:

# Frontend dependencies
bun add next@latest react@latest react-dom@latest @types/react@latest @types/react-dom@latest @t3-oss/env-nextjs@latest zod@latest zustand@latest @tanstack/react-query@latest @trpc/client@latest @trpc/react-query@latest @trpc/next@latest @react-pdf/renderer@latest react-markdown@latest remark-gfm@latest tailwindcss@latest

# Backend dependencies
bun add @trpc/server@latest drizzle-orm@latest @supabase/supabase-js@latest @supabase/ssr@latest drizzle-kit@latest postgres@latest

# Dev dependencies
bun add -d typescript@latest @types/node@latest turbo@latest

# Initialize UI libraries (run after dependencies are installed)
bunx shadcn@latest init
bunx craft-ds@latest init

Note: Craft Design System requires shadcn/ui to be initialized first, as it uses shadcn's color system.

Implementation PhasesPhase 1: Foundation & Core EditorSetup

[ ] Initialize Turbo repo
[ ] Create Next.js app structure with TypeScript
[ ] Install dependencies using Bun (use @latest for most recent versions):
- bun add next@latest react@latest react-dom@latest @types/react@latest @types/react-dom@latest @types/node@latest @t3-oss/env-nextjs@latest zod@latest @tanstack/react-query@latest @trpc/client@latest @trpc/react-query@latest @trpc/next@latest @react-pdf/renderer@latest react-markdown@latest remark-gfm@latest tailwindcss@latest
- bun add -d typescript@latest turbo@latest
- bun add @trpc/server@latest drizzle-orm@latest @supabase/supabase-js@latest drizzle-kit@latest postgres@latest
[ ] Configure root tsconfig.json with path aliases (@/app, @/packages)
[ ] Configure app-specific tsconfig.json with Next.js settings
[ ] Set up environment variables:
- [ ] Create lib/env/env.ts with @t3-oss/env-nextjs schema
- [ ] Create .env.local with required variables (DATABASE_URL, etc.)
[ ] Create next.config.ts (TypeScript format) with:
- [ ] Import env file for build-time validation
- [ ] typedRoutes: true for type-safe navigation
- [ ] Webpack path alias resolution
[ ] Set up lib folder (db, env, trpc, supabase)
[ ] Configure TailwindCSS
[ ] Configure Google Fonts (Google Sans, Google Sans Flex):
- [ ] Import fonts in app/layout.tsx using next/font/google
- [ ] Add font variables to HTML element
- [ ] Configure fonts in tailwind.config.ts
[ ] Initialize ShadCN in features/shared: bunx shadcn@latest init
[ ] Initialize Craft Design System: bunx craft-ds@latest init (requires shadcn/ui)

Editor Feature

[ ] Create features/editor structure
[ ] Implement Editor.tsx component (single responsibility)
[ ] Create useEditor.ts hook (single responsibility)
[ ] Add editor types, constants, utils
[ ] Create main editor page component (app/page.tsx)

Preview Feature

[ ] Create features/preview structure
[ ] Implement Preview.tsx component (single responsibility)
[ ] Create usePreview.ts hook (single responsibility)
[ ] Add preview types, constants, utils
[ ] Integrate react-markdown

Layout

[ ] Create split-view layout (editor | preview)
[ ] Add responsive design

Phase 2: PDF Export Feature

[ ] Create features/pdf-export structure
[ ] Implement PDFExporter.tsx component (single responsibility)
[ ] Create usePDFExport.ts hook (single responsibility)
[ ] Build pdf-generator.ts client utility (single responsibility)
[ ] Integrate @react-pdf/renderer
[ ] Add PDF styling and formatting
[ ] Implement download functionality
[ ] Add PDF export types, constants, utils

Phase 3: Backend IntegrationDatabase Setup

[ ] Set up Supabase project
[ ] Configure Supabase Auth in Supabase dashboard
[ ] Configure Drizzle schema in lib/db/schema.ts
[ ] Create database migrations
[ ] Set up Drizzle client in lib/db/client.ts

Authentication Setup

[ ] Create features/auth structure
[ ] Set up Supabase clients:
- [ ] Create browser client (lib/supabase/client.ts)
- [ ] Create server client (lib/supabase/server.ts)
- [ ] Create middleware for session refresh (middleware.ts)
[ ] Implement auth client utilities (features/auth/client/auth-client.ts)
[ ] Create useAuth.ts hook (single responsibility)
[ ] Create useSession.ts hook (single responsibility)
[ ] Create auth components:
- [ ] LoginForm.tsx (single responsibility)
- [ ] SignUpForm.tsx (single responsibility)
- [ ] UserMenu.tsx (single responsibility)
[ ] Add auth types, constants, utils

Document Feature

[ ] Create features/document structure
[ ] Implement tRPC procedures in features/document/server/document.ts
- [ ] create procedure
- [ ] getById procedure
- [ ] update procedure
- [ ] delete procedure
- [ ] list procedure
[ ] Create DocumentList.tsx component (single responsibility)
[ ] Create DocumentSave.tsx component (single responsibility)
[ ] Create useDocument.ts hook (single responsibility)
[ ] Add document types, constants, utils
[ ] Set up tRPC router in packages/api/src/router/index.ts
[ ] Create document detail page (app/documents/[id]/page.tsx)

Data Fetching

[ ] Implement server-side data fetching in page components
[ ] Pass data down to feature components
[ ] Set up React Query for client-side mutations

Phase 4: Polish & Enhancement

[ ] Add error handling (error boundaries, toast notifications)
[ ] Implement loading states
[ ] Integrate authentication in protected routes
[ ] Add user profile management
[ ] Enhance responsive design
[ ] Add keyboard shortcuts
[ ] Implement auto-save (optional)
[ ] Add document templates (optional)
[ ] Additional export formats (HTML, etc.) (optional)
[ ] Performance optimization
[ ] Testing (unit, integration, e2e)

# Project objective

user types in markdown compatible text field and it shows formatted preview on the right half of the screen.
The formatted preview can be converted to pdf and downloaded.

---

# infrastructure

- Turbo repo
- monorepo
- Bun (package manager and runtime)

## Frontend

- NextJs 16
- TailwindCSS
- Google Fonts (Google Sans, Google Sans Flex)
- Zustand - State management ([docs](https://zustand.docs.pmnd.rs/getting-started/introduction))
- ShadCN
- Craft Design System - Layout components and prose handling ([docs](https://craft-ds.com/), [GitHub](https://github.com/brijr/craft))
- @react-pdf/renderer

## Backend

- tRPC
- Drizzle
- Supabase
- Supabase Auth - User authentication

## Environment Management

- @t3-oss/env-nextjs - Type-safe environment variables with Zod validation

---

# Architecture Principles

1. **Organize by Features** - Each entity has its own feature folder with components, hooks, server, client, types, constants, utils
2. **Single Responsibility** - Components render 1 thing, hooks do 1 thing, utilities do 1 thing
3. **Component Hierarchy** - Page components → Feature components → UI components
4. **Fetch at Navigation Layer** - Fetch in server components/loaders, pass data down (or through React Query)
5. **Shared Feature Folder** - `features/shared` for shared UI components, hooks, types, server functions
6. **Lib Folder** - Low-level utilities (database, env, 3rd party clients) outside features

Let's give it a try

It didn't go as well as I thought it would—disappointed, but what did I expect? AI, let me scratch that, Large Language Models (LLMs) are bad with complexity, and to be honest, this isn't even that complex. On the bright side, it did build the foundation on which I will expand. But first, let me fix the errors:

Import paths
Monorepo workspace paths
Packages and Features in the wrong directory

Conclusion of part 1

LLMs are good at simple tasks and not good with what constitutes complexity for their capabilities. Don't get me wrong—they can build monsters—however, they can only successfully build what they've been trained on. Anything else is guessing where each piece of the puzzle fits. In short, they best serve their purpose as a tool that accelerates steps taken by a developer, writer, or noob to achieve a specific goal.

And I sure as hell will make it assist me!

I'll be back with more on this little adventure later. Time for Claude to correct this post draft. 😂

Building things, breaking things, writing about both

What's cookin'

Vibe Coding an idea into a product

From Skeptic to Believer: 4 Days to a Full SaaS Product