Getting Started with Blueprint UI

Welcome to Blueprint UI! This guide will help you quickly set up a new Next.js project pre-configured with our component library using the @fieldoffice/blueprint CLI.

Using the Blueprint CLI

The easiest way to start a new project with Blueprint UI is by using our command-line tool, @fieldoffice/blueprint. Open your terminal and run the following command:

npx @fieldoffice/blueprint init your-project-name

Replace your-project-name with the desired name for your project. The CLI will ask for the project name if you omit it. It will then create a new directory with your project name and scaffold a complete Next.js application.

What the CLI Does

The @fieldoffice/blueprint init command automates the entire setup process for you, including:

  • Creates a new Next.js 15 project with the App Router.
  • Installs React, Next.js, and all necessary Blueprint UI dependencies.
  • Sets up Tailwind CSS with the Blueprint UI theme configuration.
  • Creates essential files like app/globals.css, app/colors.css, app/buttons.css, app/typography.css, and tailwind.config.js, pre-filled with Blueprint UI defaults.
  • Provides a default app/layout.js.
  • Copies the core Blueprint UI components and the Theme Customizer into your project.
  • Configures npm scripts (dev, build, start, lint).

This means you don't need to manually install packages or copy boilerplate code. You get a production-ready setup out of the box.

Global CSS (app/globals.css)

The CLI generates an app/globals.css file that imports Tailwind's base, components, and utilities, along with Blueprint UI's core style files (colors.css, buttons.css, typography.css) and sets up base styles. Here's an example of what it looks like:

/* app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;


/* Import Blueprint UI styles */
@import './colors.css'; /* Defines CSS variables for themes (light, dark, modern) */
@import './buttons.css'; /* Base styles for buttons, customizable via Theme Customizer */
@import './typography.css'; /* Base typography styles */


@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground font-sans;
  }
  /* Additional base styles and theme handling... */
}

Tailwind Configuration (tailwind.config.js)

Your tailwind.config.js is automatically configured to use Blueprint UI's themes, colors, fonts, and animation settings. Example:

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ['class'],
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    // ... Blueprint UI theme extensions (colors, fonts, etc.) are pre-configured here
  },
  plugins: [require('tailwindcss-animate'), require('@tailwindcss/container-queries')],
}

Root Layout (app/layout.js)

A default root layout is provided in app/layout.js, ready for you to customize. Example:

import './globals.css'
import { Figtree } from 'next/font/google'


const figtree = Figtree({ subsets: ['latin'] })


export const metadata = {
  title: 'Your Blueprint App',
  description: 'Generated by @fieldoffice/blueprint CLI',
}


export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={`${figtree.className} antialiased`}>
        {children}
      </body>
    </html>
  )
}

Project Structure

After running the CLI, your project will have a structure similar to this (simplified view):

your-project-name/
├── app/
│   ├── globals.css
│   ├── colors.css
│   ├── buttons.css
│   ├── typography.css
│   ├── layout.js
│   ├── page.js
│   └── ... (other pages & routes)
├── components/
│   ├── ui/         # Core Blueprint UI components (Button, Card, etc.)
│   └── snippets/   # Pre-built UI snippets (Theme Customizer, etc.)
├── lib/
│   └── ... (utility functions, Supabase client)
├── public/
├── package.json
└── tailwind.config.js

The components/ui and components/snippets directories contain the Blueprint UI components, which you can use directly or customize further.

Running Your Project

Once the CLI has finished, navigate to your project directory and start the development server:

cd your-project-name
npm run dev

Open http://localhost:3000 in your browser to see your new Blueprint UI application.

Start Using Components

You can now start using our components in your pages. Here's a simple example:

import { Button } from '../components/ui/Button'


export default function Page() {
  return (
    <div className="p-8">
      <h1 className="h1 mb-6">Welcome</h1>
      <p className="text-body mb-4">
        This is an example page using our UI components.
      </p>
      <Button>Get Started</Button>
    </div>
  )
}

Next Steps

Start with Basic Components

Begin your journey with our Button component. It's the perfect way to understand our component patterns, styling system, and API structure.

Explore Button Component