nextjs-corgi-starter — Next.js Starter Template

SHA-256: dd0ccd057ccfa951bd03a69bd6d03bd2952de040767628f672262af84de28c30

2026-10-14T15:44:40.688Z

# Next.js + Corgi VIN Decoder Starter

A modern, production-ready Next.js starter template for building VIN decoder applications using [@cardog/corgi](https://github.com/cardog-ai/corgi) - the fastest open-source VIN decoding library.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/cardog-ai/nextjs-corgi-starter&env=NEXT_PUBLIC_CARDOG_API_URL,NEXT_PUBLIC_CARDOG_API_KEY&envDescription=Optional%20API%20credentials%20for%20server-side%20VIN%20decoding&envLink=https://cardog.ai)

![Next.js](https://img.shields.io/badge/Next.js-14-black?logo=next.js)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-CSS-38B2AC?logo=tailwind-css)

## Features

- **Dual Decoding Modes**
  - **Browser Mode**: Fully offline VIN decoding with client-side database
  - **API Mode**: Server-side decoding via Cardog API
- **Modern Stack**: Next.js 14, TypeScript, Tailwind CSS
- **Beautiful UI**: Clean, responsive interface with shadcn/ui components
- **Production Ready**: Optimized build, type-safe, error handling
- **SEO Friendly**: Server-side rendering, meta tags, sitemap ready
- **One-Click Deploy**: Deploy to Vercel with a single click

## Quick Start

### 1. Create Your Project

```bash
# Clone or download this template
npx create-next-app@latest my-vin-decoder --example https://github.com/cardog-ai/nextjs-corgi-starter

# Or clone directly
git clone https://github.com/cardog-ai/nextjs-corgi-starter.git my-vin-decoder
cd my-vin-decoder
```

### 2. Install Dependencies

```bash
npm install
# or
pnpm install
# or
yarn install
```

### 3. Configure Environment (Optional)

For API-based decoding, create a `.env.local` file:

```bash
cp .env.example .env.local
```

Edit `.env.local` and add your Cardog API credentials:

```env
NEXT_PUBLIC_CARDOG_API_URL=https://api.cardog.ai
NEXT_PUBLIC_CARDOG_API_KEY=your_api_key_here
```

> Get your free API key at [cardog.ai](https://cardog.ai)

### 4. Run Development Server

Browser mode automatically fetches the latest VPIC database from Cardog's CDN on first use - no manual download needed!

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) and start decoding VINs!

## What's Included

```
nextjs-corgi-starter/
├── app/
│   ├── layout.tsx          # Root layout with metadata
│   ├── page.tsx            # Main VIN decoder page
│   └── globals.css         # Global styles & theme
├── components/
│   ├── vin-input.tsx       # VIN input form with mode toggle
│   ├── vin-result.tsx      # Decoded vehicle information display
│   └── ui/                 # shadcn/ui components
│       ├── button.tsx
│       ├── card.tsx
│       ├── input.tsx
│       └── badge.tsx
├── lib/
│   ├── utils.ts            # Utility functions
│   ├── vin-decoder-browser.ts  # Browser-based decoder
│   └── vin-decoder-api.ts      # API-based decoder
├── public/
│   └── vpic.lite.db.gz     # VPIC database (add manually)
└── package.json
```

## Customization

### Styling

This template uses Tailwind CSS with a customizable theme. Edit `tailwind.config.ts` to change colors, fonts, and more:

```typescript
// tailwind.config.ts
theme: {
  extend: {
    colors: {
      // Add your brand colors
      brand: {
        primary: '#your-color',
        secondary: '#your-color',
      }
    }
  }
}
```

### Components

All UI components are in `components/ui/` and follow the shadcn/ui pattern. Customize them or add more:

```bash
# Add more shadcn components
npx shadcn-ui@latest add <component-name>
```

### Decoding Logic

Extend or modify the decoding logic in `lib/`:

```typescript
// lib/vin-decoder-browser.ts
export async function decodeBrowser(vin: string) {
  // Add custom preprocessing
  const cleanVin = vin.trim().toUpperCase();

  // Decode with additional options
  const result = await decodeVIN(cleanVin, adapter, {
    includePatternDetails: true, // Enable for detailed analysis
  });

  // Add custom postprocessing
  return enhanceResult(result);
}
```

## Deployment

### Deploy to Vercel (Recommended)

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/cardog-ai/nextjs-corgi-starter&env=NEXT_PUBLIC_CARDOG_API_URL,NEXT_PUBLIC_CARDOG_API_KEY&envDescription=Optional%20API%20credentials%20for%20server-side%20VIN%20decoding&envLink=https://cardog.ai)

1. Click the button above
2. Connect your GitHub account
3. Configure environment variables (if using API mode)
4. Deploy!

### Manual Deployment

```bash
# Build for production
npm run build

# Start production server
npm start
```

### Database Hosting

Browser mode fetches the latest VPIC database from Cardog's public CDN (`https://corgi.cardog.io/vpic_lite_latest.db.gz`).

The database is:
- **Always up-to-date**: Automatically updated monthly
- **Globally distributed**: Fast downloads worldwide via Cloudflare
- **Free to use**: No API key required for browser mode

Want to host your own? Modify `lib/vin-decoder-browser.ts` to point to your CDN URL.

## Usage Examples

### Basic VIN Decoding

```typescript
import { decodeBrowser } from "@/lib/vin-decoder-browser";

const result = await decodeBrowser("1HGCM82633A123456");

console.log(result.components.vehicle);
// {
//   make: 'Honda',
//   model: 'Accord',
//   year: 2003,
//   bodyStyle: 'Sedan',
//   ...
// }
```

### With Error Handling

```typescript
try {
  const result = await decodeBrowser(vin);

  if (!result.valid) {
    console.error("Invalid VIN:", result.errors);
    return;
  }

  // Use the decoded data
  displayVehicle(result.components.vehicle);
} catch (error) {
  console.error("Decode failed:", error);
}
```

## API Reference

### Browser Decoder

```typescript
import { decodeBrowser, getDatabaseStatus } from "@/lib/vin-decoder-browser";

// Decode a VIN
const result = await decodeBrowser("VIN17CHARACTERS");

// Check database status
const status = getDatabaseStatus();
console.log(status.initialized); // true/false
```

### API Decoder

```typescript
import { decodeAPI, isAPIConfigured } from "@/lib/vin-decoder-api";

// Check if API is configured
if (isAPIConfigured()) {
  const result = await decodeAPI("VIN17CHARACTERS");
}
```

## Contributing

Contributions are welcome! This template is designed to showcase [@cardog/corgi](https://github.com/cardog-ai/corgi).

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

## License

MIT License - feel free to use this template for any project!

## Acknowledgments

Built with:
- [@cardog/corgi](https://github.com/cardog-ai/corgi) - Fast, offline VIN decoding
- [Next.js](https://nextjs.org/) - React framework
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS
- [shadcn/ui](https://ui.shadcn.com/) - Beautiful components
- [Cardog](https://cardog.ai) - Automotive data platform

---

**Made by the automotive developer community**

Need help? [Open an issue](https://github.com/cardog-ai/nextjs-corgi-starter/issues) or visit [cardog.ai](https://cardog.ai)