Next.js × Antigravity Web Dev Guide — AI-Driven Full-Stack Development

Setup and context

Next.js is a React-based full-stack framework that brings server-side rendering (SSR), static generation (SSG), API routes, and the modern App Router to web development. Combined with Antigravity, you can dramatically accelerate development velocity through automated component generation, API logic implementation, and intelligent code scaffolding.

This guide demonstrates a practical workflow for building Next.js applications with Antigravity support, from initial setup through production deployment.

Project Setup and Structure

Optimal Project Architecture

# Create a Next.js project optimized for Antigravity workflows
my-nextjs-app/
├── app/                      # App Router directory
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   ├── api/                 # API routes
│   │   ├── users/
│   │   ├── posts/
│   │   ├── auth/
│   │   └── health
│   ├── dashboard/           # Protected pages
│   ├── blog/                # Blog section
│   └── error.tsx            # Error boundary
├── components/              # Reusable components
│   ├── ui/                 # Base UI components
│   ├── layouts/            # Layout components
│   ├── features/           # Feature-specific components
│   └── forms/              # Form components
├── lib/                    # Utility functions
│   ├── db.ts              # Database setup
│   ├── auth.ts            # Authentication
│   ├── api-client.ts      # API utilities
│   ├── utils.ts           # Helper functions
│   ├── schemas.ts         # Validation schemas
│   └── types.ts           # TypeScript types
├── styles/                # Global styles
├── public/                # Static assets
├── __tests__/             # Test files
├── prisma/               # Database schema
├── .env.local            # Local environment
├── next.config.js        # Next.js config
└── tsconfig.json         # TypeScript config

Installation and Dependencies

# Create Next.js project with TypeScript and Tailwind
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app
 
# Navigate to project
cd my-app
 
# Install essential dependencies
npm install prisma @prisma/client
npm install bcryptjs jsonwebtoken
npm install zod
npm install axios
npm install clsx tailwind-merge
 
# Dev dependencies
npm install -D @types/node @types/react @types/bcryptjs

Antigravity Integration Setup

Create a system prompt for optimal code generation:

# Antigravity System Prompt for Next.js Development
 
You are an expert Next.js full-stack developer.
 
Follow these practices:
 
## Component Generation
- Use React Server Components (RSC) by default
- Use "use client" only for interactive components
- Write TypeScript with explicit types
- Style with Tailwind CSS
 
## API Route Development
- Validate inputs with Zod
- Implement proper error handling
- Always check authentication
- Return consistent JSON responses
 
## Database Operations
- Use Prisma ORM
- Include complete type definitions
- Handle database errors gracefully
 
## Security
- Store secrets in environment variables
- Validate all user input
- Implement CSRF protection
- Use prepared statements

Building with App Router

Root Layout Implementation

// app/layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import '@/styles/globals.css';
import Navigation from '@/components/layouts/Navigation';
import Footer from '@/components/layouts/Footer';
import { Providers } from '@/components/Providers';
 
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
});
 
export const metadata: Metadata = {
  title: {
    default: 'My App',
    template: '%s | My App',
  },
  description: 'Built with Antigravity and Next.js',
  viewport: 'width=device-width, initial-scale=1',
  icons: {
    icon: '/favicon.ico',
  },
};
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={`${inter.variable} font-sans`}>
        <Providers>
          <Navigation />
          <main className="flex-1">
            {children}
          </main>
          <Footer />
        </Providers>
      </body>
    </html>
  );
}

Landing Page

// app/page.tsx
import Link from 'next/link';
import { Button } from '@/components/ui/Button';
import { HeroSection } from '@/components/HeroSection';
 
export default function Home() {
  return (
    <div className="min-h-screen">
      <HeroSection />
 
      <section className="py-20 px-4">
        <div className="max-w-4xl mx-auto">
          <h2 className="text-4xl font-bold mb-8 text-center">
            Features Built with Antigravity
          </h2>
 
          <div className="grid md:grid-cols-3 gap-8">
            {features.map(feature => (
              <div key={feature.id} className="p-6 border rounded-lg">
                <h3 className="text-xl font-semibold mb-2">
                  {feature.title}
                </h3>
                <p className="text-gray-600">
                  {feature.description}
                </p>
              </div>
            ))}
          </div>
        </div>
      </section>
 
      <section className="bg-blue-600 text-white py-16 px-4">
        <div className="max-w-2xl mx-auto text-center">
          <h2 className="text-3xl font-bold mb-4">
            Ready to get started?
          </h2>
          <p className="text-lg mb-8">
            Join thousands of developers building with Antigravity
          </p>
          <Link href="/signup">
            <Button className="bg-white text-blue-600 hover:bg-gray-100">
              Start Free Trial
            </Button>
          </Link>
        </div>
      </section>
    </div>
  );
}
 
const features = [
  {
    id: 1,
    title: 'AI-Powered Development',
    description: 'Generate components and APIs with natural language prompts',
  },
  {
    id: 2,
    title: 'Type-Safe Development',
    description: 'Full TypeScript support with automatic type inference',
  },
  {
    id: 3,
    title: 'Fast Deployment',
    description: 'Deploy to Vercel or Cloudflare in seconds',
  },
];

Component Generation with Antigravity

Generating UI Components

Use this Antigravity prompt:

Generate a TypeScript React component named "ProductCard"
 
Component Specifications:
- Props: product (id, title, price, image, rating)
- Style framework: Tailwind CSS
- Features:
  - Display product image with Image component
  - Show title, price, and star rating
  - Add to cart button
  - Hover animation (scale up 5%)
  - Responsive grid layout
 
Use React best practices and TypeScript types

Generated Component Example

// components/ProductCard.tsx
'use client';
 
import Image from 'next/image';
import { useState } from 'react';
import { Heart } from 'lucide-react';
import { Button } from '@/components/ui/Button';
 
interface Product {
  id: string;
  title: string;
  price: number;
  image: string;
  rating: number;
}
 
interface ProductCardProps {
  product: Product;
  onAddToCart: (productId: string) => void;
}
 
export default function ProductCard({
  product,
  onAddToCart,
}: ProductCardProps) {
  const [isFavorite, setIsFavorite] = useState(false);
 
  return (
    <div className="group bg-white rounded-lg overflow-hidden shadow-md hover:shadow-lg transition-all hover:scale-105">
      <div className="relative aspect-square overflow-hidden bg-gray-100">
        <Image
          src={product.image}
          alt={product.title}
          fill
          className="object-cover group-hover:scale-110 transition-transform"
          sizes="(max-width: 640px) 100vw, 50vw"
        />
        <button
          onClick={() => setIsFavorite(!isFavorite)}
          className="absolute top-4 right-4 p-2 bg-white rounded-full shadow"
        >
          <Heart
            size={20}
            fill={isFavorite ? 'currentColor' : 'none'}
            className={isFavorite ? 'text-red-600' : 'text-gray-400'}
          />
        </button>
      </div>
 
      <div className="p-4">
        <h3 className="font-semibold text-lg line-clamp-2 mb-2">
          {product.title}
        </h3>
 
        <div className="flex items-center justify-between mb-4">
          <span className="text-2xl font-bold">
            ${product.price.toFixed(2)}
          </span>
          <div className="flex items-center gap-1">
            <span className="text-sm font-medium">
              {product.rating.toFixed(1)}
            </span>
            <span className="text-yellow-500">★</span>
          </div>
        </div>
 
        <Button
          onClick={() => onAddToCart(product.id)}
          className="w-full"
        >
          Add to Cart
        </Button>
      </div>
    </div>
  );
}

API Route Implementation

User Management API

Antigravity prompt:

Create a Next.js API route for user management
 
Endpoint: GET /api/users
- Require JWT authentication
- Query parameters: page, limit, search
- Response: Paginated user list
- Error handling: 401 for auth, 400 for invalid params
- Validate with Zod schema

Implementation

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { verifyAuth } from '@/lib/auth';
import { db } from '@/lib/db';
 
const querySchema = z.object({
  page: z.string().regex(/^\d+$/).default('1').transform(Number),
  limit: z.string().regex(/^\d+$/).default('10').transform(Number),
  search: z.string().optional(),
});
 
export async function GET(request: NextRequest) {
  try {
    // Verify authentication
    const auth = await verifyAuth(request);
    if (!auth) {
      return NextResponse.json(
        { error: 'Unauthorized' },
        { status: 401 }
      );
    }
 
    // Validate query parameters
    const searchParams = Object.fromEntries(request.nextUrl.searchParams);
    const query = querySchema.parse(searchParams);
 
    const skip = (query.page - 1) * query.limit;
 
    // Build filter
    const where = query.search ? {
      OR: [
        { name: { contains: query.search, mode: 'insensitive' as const } },
        { email: { contains: query.search, mode: 'insensitive' as const } },
      ],
    } : undefined;
 
    // Fetch data
    const [users, total] = await Promise.all([
      db.user.findMany({
        where,
        skip,
        take: query.limit,
        select: {
          id: true,
          name: true,
          email: true,
          createdAt: true,
        },
      }),
      db.user.count({ where }),
    ]);
 
    return NextResponse.json({
      data: users,
      pagination: {
        page: query.page,
        limit: query.limit,
        total,
        pages: Math.ceil(total / query.limit),
      },
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Invalid query parameters', issues: error.issues },
        { status: 400 }
      );
    }
 
    console.error('Users API error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Creating Users

// app/api/users/route.ts (POST handler)
import { hashPassword } from '@/lib/auth';
 
const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  password: z.string().min(8),
});
 
export async function POST(request: NextRequest) {
  try {
    const auth = await verifyAuth(request);
    if (!auth || !auth.isAdmin) {
      return NextResponse.json(
        { error: 'Forbidden' },
        { status: 403 }
      );
    }
 
    const body = await request.json();
    const { name, email, password } = createUserSchema.parse(body);
 
    // Check if user exists
    const existing = await db.user.findUnique({
      where: { email },
    });
 
    if (existing) {
      return NextResponse.json(
        { error: 'User already exists' },
        { status: 409 }
      );
    }
 
    // Hash password and create user
    const hashedPassword = await hashPassword(password);
    const user = await db.user.create({
      data: {
        name,
        email,
        passwordHash: hashedPassword,
      },
    });
 
    return NextResponse.json(
      {
        id: user.id,
        name: user.name,
        email: user.email,
      },
      { status: 201 }
    );
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Invalid input', issues: error.issues },
        { status: 400 }
      );
    }
 
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Authentication System

JWT Authentication

// lib/auth.ts
import jwt from 'jsonwebtoken';
import bcryptjs from 'bcryptjs';
import { NextRequest } from 'next/server';
 
const JWT_SECRET = process.env.JWT_SECRET || '';
const JWT_EXPIRY = '7d';
 
export interface AuthPayload {
  userId: string;
  email: string;
  isAdmin?: boolean;
}
 
export function createToken(payload: AuthPayload): string {
  return jwt.sign(payload, JWT_SECRET, {
    expiresIn: JWT_EXPIRY,
  });
}
 
export function verifyToken(token: string): AuthPayload | null {
  try {
    return jwt.verify(token, JWT_SECRET) as AuthPayload;
  } catch (error) {
    return null;
  }
}
 
export async function verifyAuth(
  request: NextRequest
): Promise<AuthPayload | null> {
  const authHeader = request.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return null;
  }
 
  const token = authHeader.slice(7);
  return verifyToken(token);
}
 
export async function hashPassword(password: string): Promise<string> {
  const salt = await bcryptjs.genSalt(10);
  return bcryptjs.hash(password, salt);
}
 
export async function verifyPassword(
  password: string,
  hash: string
): Promise<boolean> {
  return bcryptjs.compare(password, hash);
}

Login Endpoint

// app/api/auth/login/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { db } from '@/lib/db';
import { createToken, verifyPassword } from '@/lib/auth';
 
const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
});
 
export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { email, password } = loginSchema.parse(body);
 
    const user = await db.user.findUnique({
      where: { email },
    });
 
    if (!user) {
      return NextResponse.json(
        { error: 'Invalid credentials' },
        { status: 401 }
      );
    }
 
    const isValidPassword = await verifyPassword(
      password,
      user.passwordHash
    );
 
    if (!isValidPassword) {
      return NextResponse.json(
        { error: 'Invalid credentials' },
        { status: 401 }
      );
    }
 
    const token = createToken({
      userId: user.id,
      email: user.email,
      isAdmin: user.isAdmin,
    });
 
    return NextResponse.json({
      token,
      user: {
        id: user.id,
        name: user.name,
        email: user.email,
      },
    });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Invalid input' },
        { status: 400 }
      );
    }
 
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Styling with Tailwind CSS

Global Styles

/* styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
@layer base {
  html {
    @apply scroll-smooth;
  }
 
  body {
    @apply bg-white dark:bg-slate-950 transition-colors;
  }
 
  h1 {
    @apply text-4xl font-bold;
  }
 
  h2 {
    @apply text-3xl font-bold;
  }
}
 
@layer components {
  .btn-base {
    @apply inline-flex items-center justify-center px-4 py-2 rounded-lg font-medium transition-colors;
  }
 
  .btn-primary {
    @apply btn-base bg-blue-600 text-white hover:bg-blue-700;
  }
 
  .btn-secondary {
    @apply btn-base bg-gray-200 text-gray-900 hover:bg-gray-300;
  }
 
  .form-input {
    @apply w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500;
  }
}

Tailwind Configuration

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          600: '#2563eb',
          900: '#1e40af',
        },
      },
      fontFamily: {
        sans: ['var(--font-inter)', 'system-ui', 'sans-serif'],
      },
      animation: {
        fadeIn: 'fadeIn 0.3s ease-in',
      },
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
      },
    },
  },
  plugins: [],
};

Deployment

Vercel Deployment

# Install Vercel CLI
npm install -g vercel
 
# Deploy to preview
vercel
 
# Deploy to production
vercel --prod
 
# Set environment variables in dashboard
# Project Settings > Environment Variables

Cloudflare Pages Deployment

# Build for static export
npm run build
 
# Install Wrangler CLI
npm install -g wrangler
 
# Authenticate
wrangler login
 
# Deploy
wrangler pages deploy ./out

Environment Variables

# .env.local
DATABASE_URL="postgresql://..."
JWT_SECRET="your-secret-key"
NODE_ENV="development"
 
# .env.production (set in hosting dashboard)
DATABASE_URL="postgresql://..."
JWT_SECRET="your-secret-key"
NODE_ENV="production"

Performance Optimization

Image Optimization

// components/OptimizedImage.tsx
import Image from 'next/image';
 
interface OptimizedImageProps {
  src: string;
  alt: string;
  width: number;
  height: number;
}
 
export function OptimizedImage({
  src,
  alt,
  width,
  height,
}: OptimizedImageProps) {
  return (
    <Image
      src={src}
      alt={alt}
      width={width}
      height={height}
      loading="lazy"
      placeholder="blur"
      blurDataURL="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    />
  );
}

API Response Caching

// lib/cache.ts
import { headers } from 'next/headers';
 
export function withCache(
  fn: (args: any) => Promise<any>,
  ttl: number = 3600
) {
  return async (args: any) => {
    const headersList = headers();
    const cacheKey = `${args.query}:${JSON.stringify(args.params)}`;
 
    // Implement with Redis or similar
    const cached = await getCachedValue(cacheKey);
    if (cached) return cached;
 
    const result = await fn(args);
    await setCachedValue(cacheKey, result, ttl);
 
    return result;
  };
}

Testing

API Testing

// __tests__/api/users.test.ts
import { GET } from '@/app/api/users/route';
import { NextRequest } from 'next/server';
 
describe('GET /api/users', () => {
  it('returns 401 without authentication', async () => {
    const req = new NextRequest('http://localhost:3000/api/users');
    const res = await GET(req);
 
    expect(res.status).toBe(401);
  });
 
  it('returns paginated users with valid auth', async () => {
    const req = new NextRequest(
      'http://localhost:3000/api/users?page=1&limit=10',
      {
        headers: {
          'Authorization': 'Bearer valid-token',
        },
      }
    );
 
    const res = await GET(req);
    expect(res.status).toBe(200);
 
    const data = await res.json();
    expect(data).toHaveProperty('data');
    expect(data).toHaveProperty('pagination');
  });
});

Best Practices Summary

Use Server Components by default - Reduces client-side JavaScript
Validate all inputs - Use Zod for consistent validation
Implement proper error handling - Return meaningful error messages
Secure API routes - Always verify authentication and authorization
Optimize images and assets - Use Next.js Image component
Cache strategically - Use ISR, SWR, or API response caching
Monitor performance - Use Web Vitals and error tracking
Environment variable management - Keep secrets secure

Conclusion

Combining Antigravity with Next.js enables rapid, type-safe full-stack development. The AI-powered code generation dramatically reduces boilerplate while maintaining best practices and security. Deploy your Next.js applications with confidence to Vercel, Cloudflare, or any other platform.