Quick start

This guide will help you understand the boilerplate by exploring its features. You'll experience the landing page, create an account, and test the authentication system in action.

Goal

By the end of this guide, you'll have:

1. Started the development server
2. Explored the landing page
3. Created a user account
4. Tested the authentication system
5. Experienced the included features

Let's get started!

Prerequisites

Make sure you've completed the installation guide and have:

• ✅ Installed dependencies
• ✅ Set up your database
• ✅ Configured environment variables

Step 1: Start the development server

If you haven't already, start your development server:

pnpm dev

Your app will be running at http://localhost:3000.

Step 2: Explore the landing page

Before creating an account, let's check out the landing page at http://localhost:3000.

You'll see:

• Modern hero section - A clean, professional landing page design.
• Feature showcase - Highlights of what's included in the boilerplate.
• Call-to-action buttons - Try clicking "Get started" or "View documentation".
• Responsive design - Resize your browser to see how it adapts to different screen sizes.
• Dark/light mode - Toggle the theme using the button in the header.

Step 3: Create an account and test

Now let's test the authentication system and explore the protected features!

3.1 Register a new account

1. Navigate to registration - Go to http://localhost:3000/auth/register
2. Fill in your details:
   • Name: Your name
   • Email: A valid email address
   • Password: At least 8 characters, with at least one uppercase letter and one number
3. Submit - Click "Create account"

3.2 Explore the dashboard

1. Navigate to dashboard - After logging in, you'll be redirected to the dashboard at http://localhost:3000/app/dashboard
2. Explore the UI - Check out the pre-built dashboard with beautiful shadcn-vue components
3. Try the navigation - Use the header menu to explore different pages like Profile and Settings
4. Return to landing page - Click the logo or navigate back to / and notice how the header changes for authenticated users
5. Test protected routes - Try logging out and accessing /app/dashboard or /app/settings. You'll be automatically redirected to the login page. This is the auth middleware in action!

What you learned

Through this hands-on tutorial, you've experienced:

• ✅ Development server - Started the Nuxt development environment
• ✅ Landing page - Explored the modern, responsive landing page design
• ✅ Global auth protection - Saw how routes are automatically secured
• ✅ User store - Experienced authentication state management with Pinia
• ✅ shadcn-vue components - Explored pre-built UI components
• ✅ Authentication flow - Registered, logged in, and tested protected routes
• ✅ File-based routing - Navigated between different pages

Key concepts explained

Global authentication middleware

The boilerplate uses a global middleware (app/middleware/auth.global.ts) that automatically protects all routes except those defined in the public routes list:

const publicPrefixes = ['/auth/', '/blog/', '/checkout/', '/docs']
const exactPublicRoutes = ['/', '/pricing', '/download']

How it works:

• Routes matching these patterns → Public (no auth required)
• All other routes (like /app/dashboard, /app/settings) → Protected (auth required)
• Unauthenticated users → Automatically redirected to /auth/login
• Authenticated users trying to access /auth/* → Redirected to /

User store

const userStore = useUserStore()
const { user } = storeToRefs(userStore)

The user store (Pinia) holds the current user's authentication state. Using storeToRefs ensures reactivity when accessing store properties.

Shadcn-vue components

The boilerplate includes 170+ pre-built UI components. They're automatically imported, so you can use them directly:

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    Content here
  </CardContent>
</Card>

Next steps

Now that you understand the basics, explore more features:

Troubleshooting

Can't access protected pages

• Make sure you're logged in - check the header for your user menu
• Try refreshing the page - the session might not have loaded yet
• Check the browser console for errors

Changes not showing up

• Make sure the dev server is running (pnpm dev)
• Try hard-refreshing the browser (Ctrl+Shift+R or Cmd+Shift+R)
• Check that you saved the file

Authentication not working

• Make sure your database is running and migrations have been applied
• Check your .env file has the correct BETTER_AUTH_SECRET value
• Clear browser cookies and try registering again