We strongly recommend using VS Code or Cursor for building with Vibestacks. Both editors provide excellent TypeScript support and have extensions that make working with our stack significantly easier.

Cursor recommended

If you're new to both editors, we recommend Cursor. It's built on VS Code (so all extensions work) but adds powerful AI features that speed up development considerably.

Recommended Extensions

When you open Vibestacks in VS Code or Cursor, you should be prompted to install our recommended extensions. If not, install these manually:

Essential

Extension	Purpose
ESLint	Catches errors and enforces code quality
Prettier	Automatic code formatting
Tailwind CSS IntelliSense	Autocomplete for Tailwind classes

Highly Recommended

Extension	Purpose
Pretty TypeScript Errors	Makes TypeScript errors human-readable
Error Lens	Shows errors inline, right where they occur
GitLens	Git blame, history, and more
Auto Rename Tag	Automatically rename paired HTML/JSX tags

Optional but Nice

Extension	Purpose
Console Ninja	See console.log output inline in your editor
Todo Tree	Track TODOs and FIXMEs across your codebase
Import Cost	See the size of imported packages

Workspace Settings

For the best experience, add these settings to your VS Code/Cursor configuration. Create or update .vscode/settings.json:

.vscode/settings.json

{
  // Format and fix on save
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },

  // TypeScript
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "typescript.suggest.autoImports": true,

  // Tailwind CSS v4
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },

  // File nesting (cleaner file tree)
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.patterns": {
    "package.json": "package-lock.json, pnpm-lock.yaml, yarn.lock, .npmrc",
    "tsconfig.json": "tsconfig.*.json",
    ".env": ".env.*",
    "postcss.config.*": "postcss.config.*"
  },

  // Hide noise
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.next": true
  }
}

What's classRegex?

The classRegex setting enables Tailwind autocomplete inside cn() and cva() functions - not just in className="". These utilities are how Vibestacks handles conditional and variant-based styling. Learn more in Why We Use cn() and cva() for Component Styling.

Tailwind CSS v4

Vibestacks uses Tailwind CSS v4, which configures themes directly in CSS using @theme instead of a tailwind.config.ts file. The IntelliSense extension works the same way - just make sure to associate .css files with tailwindcss for proper syntax highlighting.

Commit this file

Add .vscode/settings.json to version control so your team shares the same configuration.

Path Aliases

Vibestacks uses the @/ path alias to simplify imports. Instead of relative paths like ../../../components/Button, you can write:

import { Button } from "@/components/ui/button";
import { db } from "@/db";
import { env } from "@/env";

This is configured in tsconfig.json:

tsconfig.json (excerpt)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Your editor will automatically resolve these paths and provide autocomplete.

Cursor AI Setup

Cursor supercharges your development with AI. Here's how to get the most out of it with Vibestacks.

Add Documentation Sources

Cursor can reference official documentation when answering questions. Add the libraries we use:

Open Cursor Settings

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and search for "Cursor Settings" or click the gear icon.

Navigate to Docs

Go to Features → Docs.

Add Documentation URLs

Click Add Doc and add each of these:

Library	URL
Next.js	`https://nextjs.org/docs`
Drizzle ORM	`https://orm.drizzle.team/docs`
shadcn/ui	`https://ui.shadcn.com/docs`
Better Auth	`https://better-auth.com/docs`
Tailwind CSS	`https://tailwindcss.com/docs`
Fumadocs	`https://fumadocs.vercel.app/docs`

Now when you ask Cursor about these libraries, it will reference the official docs for accurate answers.

Effective Prompting Tips

Get better results from Cursor with these patterns:

Good prompts

✅ "Create a server action that creates a new post using Drizzle"
✅ "Add a protected API route that requires authentication with Better Auth"
✅ "Build a form component using shadcn/ui with react-hook-form validation"

Less effective prompts

❌ "Make a form" (too vague)
❌ "Fix this" (no context)

Coming soon: Cursor Rules

We're working on custom Cursor rules that will ship with Vibestacks. These will give the AI context about our specific patterns and conventions, making it even more helpful.

Keyboard Shortcuts

These shortcuts will save you time every day:

Essential Shortcuts

Action	Mac	Windows/Linux
Command Palette	`Cmd+Shift+P`	`Ctrl+Shift+P`
Quick Open (files)	`Cmd+P`	`Ctrl+P`
Go to Symbol	`Cmd+Shift+O`	`Ctrl+Shift+O`
Toggle Terminal	Ctrl+`	Ctrl+`
Toggle Sidebar	`Cmd+B`	`Ctrl+B`

TypeScript Shortcuts

Action	Mac	Windows/Linux
Go to Definition	`Cmd+Click` or `F12`	`Ctrl+Click` or `F12`
Find All References	`Shift+F12`	`Shift+F12`
Rename Symbol	`F2`	`F2`
Quick Fix	`Cmd+.`	`Ctrl+.`
Restart TS Server	`Cmd+Shift+P` → "Restart TS"	`Ctrl+Shift+P` → "Restart TS"

Cursor AI Shortcuts

Action	Mac	Windows/Linux
Inline Edit	`Cmd+K`	`Ctrl+K`
Chat	`Cmd+L`	`Ctrl+L`
Composer	`Cmd+I`	`Ctrl+I`
Accept Suggestion	`Tab`	`Tab`

Restart TS Server

If you're seeing stale type errors or autocomplete isn't working, restart the TypeScript server. This is especially common after schema changes or pulling new code.

Tailwind CSS v4

Vibestacks uses Tailwind CSS v4, which has a new CSS-based configuration system. Instead of a tailwind.config.ts file, themes are defined directly in CSS.

Deep dive

Want to understand the full picture? Read Tailwind CSS v4: What Changed and Why It's Better for a complete breakdown of the new architecture.

Configuration Location

All Tailwind configuration lives in app/globals.css:

app/globals.css

@import "tailwindcss";
@import "tw-animate-css";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... more theme tokens */
}

Key Differences from v3

Feature	Tailwind v3	Tailwind v4
Config file	`tailwind.config.ts`	`@theme` in CSS
Custom colors	`theme.extend.colors`	`--color-*` CSS variables
Animations	`theme.extend.keyframes`	`@keyframes` in `@theme`
Dark mode	`darkMode: 'class'`	`@custom-variant dark`
PostCSS plugin	`tailwindcss`	`@tailwindcss/postcss`

Adding Custom Styles

To add new theme tokens, extend the @theme inline block:

Adding a custom color

@theme inline {
  /* Existing tokens... */
  
  --color-brand: oklch(0.6 0.2 250);
  --color-brand-foreground: oklch(0.98 0 0);
}

Then use it in your components:

<div className="bg-brand text-brand-foreground">
  Branded content
</div>

Vibestacks includes ESLint configured with Next.js best practices.

ESLint Configuration

The ESLint config extends Next.js recommended rules:

eslint.config.js

import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTs from "eslint-config-next/typescript";

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  globalIgnores([
    ".next/**",
    "out/**",
    "build/**",
    "next-env.d.ts",
  ]),
]);

export default eslintConfig;

Running Linting

Check for issues

pnpm lint

With the recommended VS Code settings, ESLint will automatically fix issues on save.

Debugging

VS Code and Cursor have built-in debugging for Next.js. Create this configuration to enable breakpoints:

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "pnpm dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "args": ["dev"],
      "console": "integratedTerminal",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

Press F5 to start debugging with breakpoints.

Recommended File Structure

When adding new features, follow this structure:

layout.tsx

page.tsx

Directory	Purpose
`app/`	Next.js App Router pages and layouts
`app/(group)/`	Route groups for shared layouts
`app/api/`	API routes and webhooks
`components/`	React components
`components/ui/`	shadcn/ui primitives
`lib/`	Utility functions and shared logic
`db/`	Database schema and client

Troubleshooting

TypeScript errors not updating

Restart the TypeScript server:

Cmd+Shift+P → "TypeScript: Restart TS Server"

Tailwind autocomplete not working

Ensure Tailwind CSS IntelliSense extension is installed
Check that your app/globals.css has @import "tailwindcss" at the top
Verify .vscode/settings.json has "files.associations": { "*.css": "tailwindcss" }
Restart VS Code/Cursor

ESLint not running on save

Check that ESLint extension is installed and enabled
Verify .vscode/settings.json has "source.fixAll.eslint": "explicit"
Check the ESLint output panel for errors (View → Output → ESLint)

Imports not resolving

Ensure tsconfig.json has the path aliases configured
Restart the TypeScript server
Run pnpm install to ensure dependencies are installed

Next Steps

Your development environment is ready! Continue with:

Project Structure - Understand how the codebase is organized
Authentication - Set up user authentication
Database - Configure your database

IDE Setup

Recommended Extensions

Essential

Highly Recommended

Optional but Nice

Workspace Settings

Path Aliases

Cursor AI Setup

Add Documentation Sources

Open Cursor Settings

Navigate to Docs

Add Documentation URLs

Effective Prompting Tips

Keyboard Shortcuts

Essential Shortcuts

TypeScript Shortcuts

Cursor AI Shortcuts

Tailwind CSS v4

Configuration Location

Key Differences from v3

Adding Custom Styles

ESLint Configuration

Running Linting

Debugging

Recommended File Structure

Troubleshooting

TypeScript errors not updating

Tailwind autocomplete not working

ESLint not running on save

Imports not resolving

Next Steps

On this page