Velocity: My Nuxt + Bun Starter Template for Lightning-Fast MVP Development

Three Hours to Build What Used to Take Three Days

I had an idea for a side project on Tuesday evening. By Wednesday afternoon, I had a working prototype with authentication, a responsive UI, and proper TypeScript setup. A year ago, that would have taken me three full days just to get the infrastructure right.

The difference? Velocity — my own Nuxt starter template that I built after getting tired of setting up the same boilerplate for every new project.

In this post, I'll share why I created Velocity, what problems it solves, and how you can use it to ship MVPs faster without sacrificing code quality.

The Problem: Setup Fatigue is Real

The Last Straw

I was starting yet another side project. A simple idea: a tool to help developers share code snippets with syntax highlighting and GitHub OAuth login.

Here's what I had to do before writing a single line of actual feature code:

# Day 1: The Setup Marathon
npx nuxi@latest init my-project
cd my-project
npm install

# Configure TypeScript
# Set up ESLint and Prettier
# Install and configure Tailwind or UnoCSS
# Set up Pinia for state management
# Configure environment variables
# Set up Supabase project
# Install Supabase client
# Configure OAuth provider on Supabase dashboard
# Create GitHub OAuth app
# Wire up authentication middleware
# Create login/logout components
# Set up protected routes
# Configure auto-imports
# Set up proper folder structure

By the time everything was working, my initial excitement had faded. I spent two full days on infrastructure before touching my actual idea.

Sound familiar?

The Real Cost of Reinventing the Wheel

Every new project meant:

• 2-3 days of initial setup
• Copying configs from old projects (hoping they still work)
• Fighting version conflicts between dependencies
• Rediscovering gotchas I'd solved before
• Losing momentum before building the actual feature

I thought: "There has to be a better way."

Enter Velocity: A Template Built from Battle Scars

I decided to create a template that included everything I needed for 90% of my projects:

• Modern tech stack that I actually enjoy using
• Authentication pre-configured because every app needs it
• TypeScript because I'm done debugging runtime errors
• Fast development experience with Bun
• Beautiful defaults so I can start building features immediately

Why "Velocity"?

The name came naturally. I wanted to move fast without breaking things. Ship ideas quickly. Go from concept to deployed MVP in hours, not days.

Velocity = Speed + Direction. That's exactly what this template provides.

The Tech Stack: Why These Choices?

Nuxt 4 - The Progressive Vue Framework

// nuxt.config.ts - Clean, powerful configuration
export default defineNuxtConfig({
    compatibilityDate: "2025-10-17",
    devtools: { enabled: true },
    extends: [resolve("../../layers/base")],
});

Why Nuxt over other frameworks?

I tried Next.js, SvelteKit, and others. Here's why Nuxt won:

1. Auto-imports everywhere - Components, composables, utilities
2. File-based routing that actually makes sense
3. Built-in state management with Pinia
4. Server-side rendering without configuration hell
5. Vue 3 Composition API - cleaner than React hooks (fight me)

My experience: After building a project in Next.js and then rebuilding it in Nuxt, I saved roughly 30% of the code and had better TypeScript support.

Bun - Lightning-Fast Runtime

# Install dependencies
bun install  # ⚡ 2-3x faster than npm

# Start dev server  
bun dev      # Instant hot reload

# Run production build
bun build    # Blazing fast builds

Why Bun over npm/pnpm/yarn?

• Speed: Dependencies install in seconds, not minutes
• Built-in TypeScript: No need for ts-node
• Native test runner: Testing without extra deps
• Drop-in replacement: All npm packages work
• Future-proof: The JavaScript ecosystem is moving this direction

Real numbers: npm install on Velocity: ~45 seconds. bun install: ~8 seconds. That adds up fast.

Supabase + GitHub OAuth - Authentication Without Tears

This was the game-changer. Authentication used to be my least favorite part of any project.

<!-- Before Velocity: Complex auth setup -->
<!-- After Velocity: It just works -->

<script setup>
const user = useSupabaseUser();  // Auto-imported
const supabase = useSupabaseClient();  // Auto-imported

async function signInWithGitHub() {
    const { error } = await supabase.auth.signInWithOAuth({
        provider: "github",
        options: {
            redirectTo: `${window.location.origin}/home`
        }
    });
}
</script>

<template>
    <div v-if="user">
        Welcome, {{ user.user_metadata.name }}!
    </div>
    <button v-else @click="signInWithGitHub">
        Continue with GitHub
    </button>
</template>

What's included:

• GitHub OAuth pre-configured (just add your keys)
• Protected routes with middleware
• Auto-refresh tokens
• Session persistence
• Logout functionality
• User state management

The best part? It takes 5 minutes to set up your OAuth credentials, then authentication just works.

TypeScript - Because Life's Too Short for Runtime Errors

// Full type safety everywhere
export const useCounterStore = defineStore("counter", () => {
    const count = ref<number>(0);

    function increment(): void {
        count.value++;
    }

    return { count, increment };
});

// TypeScript catches mistakes before they become bugs
const counterStore = useCounterStore();
counterStore.count = "hello";  // ❌ TypeScript error - caught at dev time!

Why TypeScript in every template?

After three painful production bugs that TypeScript would have caught in 2 seconds, I made a rule: no more JavaScript-only projects.

UnoCSS - Tailwind's Faster Cousin

<!-- Beautiful, utility-first CSS without the bloat -->
<div class="flex items-center justify-center bg-gray-950 text-white p-8 rounded-lg">
    <h1 class="text-4xl font-bold">Hello Velocity</h1>
</div>

Why UnoCSS over Tailwind?

• Instant: On-demand CSS generation (only what you use)
• Smaller bundle: No purging needed
• Same syntax: If you know Tailwind, you know UnoCSS
• Faster builds: Vite-native performance

Roboto font pre-configured because I'm tired of looking at system fonts during development.

What's Inside Velocity?

Complete Project Structure

velocity/
├── app/
│   ├── components/        # Auto-imported Vue components
│   │   ├── AppHeader.vue  # Navigation with auth
│   │   └── AppFooter.vue  # Footer component
│   ├── layouts/           # Nuxt layouts
│   │   └── default.vue    # Default layout
│   ├── middleware/        # Route middleware
│   │   └── auth.global.ts # Global auth protection
│   ├── pages/             # File-based routing
│   │   ├── index.vue      # Landing page
│   │   ├── login.vue      # GitHub OAuth login
│   │   └── home.vue       # Protected home page
│   └── stores/            # Pinia stores
│       └── CounterStore.ts # Example store
├── lib/
│   └── constants.ts       # App constants
├── .env                   # Environment variables
└── nuxt.config.ts         # Nuxt configuration

Authentication Flow (The Part That Used to Be Hard)

Here's what happens when a user logs in:

1. User clicks "Continue with GitHub"
2. Redirects to GitHub authorization
3. User approves the app
4. GitHub redirects back with tokens
5. Supabase processes authentication automatically
6. User lands on protected /home page
7. Auth state syncs across all components

The code that makes it work:

// app/middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to) => {
    const user = useSupabaseUser();
    const isAuthenticated = user.value !== null;

    // Redirect logic
    if (to.path === "/login" && isAuthenticated) {
        return navigateTo("/home");
    }

    if (to.path === "/home" && !isAuthenticated) {
        return navigateTo("/login");
    }
});

That's it. Route protection with reactive auth state.

State Management with Pinia

// app/stores/CounterStore.ts - Example store included
export const useCounterStore = defineStore("counter", () => {
    const count = ref(0);
    
    function increment() {
        count.value++;
    }
    
    function decrement() {
        count.value--;
    }

    return { count, increment, decrement };
});

Usage in components:

<script setup>
const counterStore = useCounterStore();  // Auto-imported!
</script>

<template>
    <div>
        <p>Count: {{ counterStore.count }}</p>
        <button @click="counterStore.increment">+</button>
    </div>
</template>

ESLint Configuration (So You Don't Have To)

Pre-configured with:

• @antfu/eslint-config - Best practices built-in
• Security plugins - Catch vulnerabilities early
• Nuxt-specific rules - Optimized for Nuxt development
• Consistent formatting - 4-space indent, double quotes, semicolons

Getting Started in 5 Minutes

Step 1: Clone and Install

# Clone the template
git clone https://github.com/ojaswiat/velocity my-project
cd my-project

# Install dependencies with Bun
bun install

Step 2: Set Up Supabase (One Time, 3 Minutes)

1. Create Supabase project at supabase.com
2. Get your credentials from Settings → API
3. Create .env file:

NUXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NUXT_PUBLIC_SUPABASE_KEY=your-anon-key

Step 3: Configure GitHub OAuth (2 Minutes)

1. Go to GitHub Developer Settings
2. Create new OAuth App
3. Set callback URL: https://your-project.supabase.co/auth/v1/callback
4. Copy Client ID and Secret
5. Add them to Supabase (Authentication → Providers → GitHub)

Step 4: Start Building

bun dev

Visit http://localhost:3000. Everything works. Start building your actual features.

Real-World Usage: My Recent Projects

Project 1: DevSnippet (Shipped in 2 Days)

A tool for developers to share code snippets with syntax highlighting.

What Velocity provided:

• Authentication system (users can save their snippets)
• TypeScript for editor integration types
• UnoCSS for beautiful code card layouts
• Pinia for managing user snippets state

What I built:

• Code editor integration
• Syntax highlighting
• Snippet CRUD operations
• Sharing functionality

Time saved: Estimated 2 full days on auth and infrastructure setup.

Project 2: ReadingList (Shipped in 1 Day)

A personal reading list manager with GitHub login.

Time from idea to deployed MVP: 8 hours (including breaks).

This would have been impossible without Velocity. The authentication alone used to take longer than that.

Common Mistakes to Avoid

Mistake 1: Not Setting Up Environment Variables

# ❌ Starting dev server without .env
bun dev  # Crashes with "Missing Supabase credentials"

# ✅ Always copy and configure .env first
cp env .env
# Edit .env with your credentials
bun dev  # Now it works!

Mistake 2: Wrong OAuth Callback URL

The GitHub OAuth callback URL must be:

https://your-project-ref.supabase.co/auth/v1/callback

Not your app URL. Not localhost. Your Supabase URL.

Mistake 3: Forgetting to Enable GitHub Provider

Even with correct credentials, you need to:

1. Go to Supabase Dashboard
2. Authentication → Providers
3. Find GitHub
4. Toggle it ON
5. Save changes

Deploying to Production

When you're ready to deploy:

# Build for production
bun build

# Deploy to Vercel, Netlify, or Cloudflare Pages
# They all support Nuxt SSR out of the box

Don't forget:

1. Set environment variables in your hosting platform
2. Update GitHub OAuth app with production URL
3. Update Supabase redirect URLs with production domain

Extending Velocity for Your Needs

Adding Database Queries

// Velocity includes Supabase client auto-imported
const supabase = useSupabaseClient();

// Fetch data from your database
const { data: posts } = await supabase
    .from("posts")
    .select("*")
    .order("created_at", { ascending: false });

Adding More Protected Routes

// app/middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to) => {
    const user = useSupabaseUser();
    const isAuthenticated = user.value !== null;

    const protectedRoutes = ["/home", "/dashboard", "/profile"];

    if (protectedRoutes.includes(to.path) && !isAuthenticated) {
        return navigateTo("/login");
    }
});

Adding More OAuth Providers

Velocity uses @nuxtjs/supabase, which supports:

• Google
• Facebook
• Twitter
• Discord
• And more

Just enable them in Supabase and use the same pattern:

await supabase.auth.signInWithOAuth({
    provider: "google",  // or "discord", "twitter", etc.
    options: {
        redirectTo: `${window.location.origin}/home`
    }
});

Why Build Your Own Template?

You might ask: "Why not use one of the hundreds of existing templates?"

Here's why I built my own:

1. I know every line of code - No mystery dependencies or unused features
2. It matches my workflow - Organized exactly how I think
3. It's opinionated - No decision fatigue on every project
4. It's maintained - I use it regularly, so it stays updated
5. It grows with me - As I learn better patterns, the template evolves

The template paradox: The best template is the one you built yourself, because it solves your problems.

But I'm sharing Velocity because maybe we have similar problems.

What Velocity is NOT

Let's be clear about what this isn't:

• Not a framework - It's a starter template
• Not a CMS - It's for building web apps, not content sites
• Not zero-config - You still need to add your OAuth keys
• Not a silver bullet - You still need to build your features

Velocity gives you a fantastic starting point, but you do the creative work.

Future Improvements I'm Planning

Based on my usage and feedback from friends using it:

• More auth providers out of the box
• Database schema examples for common use cases
• API route examples for different patterns
• Testing setup with Vitest
• Docker configuration for containerized deployment
• CI/CD examples for automated deployments

The Velocity Philosophy

This template embodies a few core beliefs:

1. Start fast, iterate fast - Ship MVPs in hours, not weeks
2. Modern by default - Use the latest stable tech
3. Less is more - Include what's needed, nothing extra
4. Developer experience matters - Fast dev server, good errors, clear structure
5. Production-ready - Not just a toy, but a foundation for real apps

Should You Use Velocity?

Velocity is perfect for you if:

• You build web apps with Vue/Nuxt
• You need authentication in your projects
• You want TypeScript but hate setup
• You value fast iteration over custom infrastructure
• You're building MVPs, side projects, or startups

Velocity might NOT be for you if:

• You need server-side rendering with extreme customization
• You're building a content-heavy blog (use Nuxt Content instead)
• You prefer React ecosystem (check out Next.js templates)
• You need a specific tech stack that differs significantly

Conclusion: Build MVPs Fast, Ship Ideas Faster

Creating Velocity saved me hundreds of hours across multiple projects. More importantly, it removed the friction between having an idea and seeing it work.

Now when inspiration strikes, I don't think: "Ugh, I need to set up authentication again."

I think: "I can have this working by tomorrow."

That shift in mindset is everything for side projects and MVPs.

If you're building web applications with Vue and keep repeating the same setup steps, consider building your own template. Or fork Velocity and make it yours.

The goal isn't to use my template forever—it's to stop wasting time on setup and start shipping your ideas.

Check out Velocity on GitHub. Star it, fork it, break it, improve it. Make it your own.

And then go build something amazing with it.

If this inspires you to build your own starter template or helps you ship your next MVP faster, I'd love to hear about it! Connect with me on Twitter or LinkedIn for more web development insights.

Support My Work

If this template saves you hours of setup time, helps you ship your MVP faster, or inspires you to build your own tools, I'd greatly appreciate your support! Creating and maintaining templates, writing comprehensive guides, and sharing knowledge takes significant time and effort. Your contribution helps me continue building tools that make developers' lives easier.

☕ Buy me a coffee - Every contribution, big or small, means the world to me and keeps me motivated to create more content!

Cover image by CHUTTERSNAP on Unsplash