create-velocity-astro

Scaffold production-ready Velocity projects in seconds.

Velocity is an opinionated Astro 6 + Tailwind CSS v4 starter kit with 27+ components, i18n support, SEO optimization, and deployment-ready configuration.

Quick Start

``bash


npm

npm create velocity-astro@latest my-site

pnpm (recommended)

pnpm create velocity-astro my-site

yarn

yarn create velocity-astro my-site

bun

bun create velocity-astro my-site
`

CLI Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| --demo | boolean | prompt | Include demo landing page and sample content |
| --components | string | prompt | Component selection (see below) |
| --i18n | boolean | prompt | Add internationalization support |
| --pages | boolean | false | Generate starter pages interactively |
| -y, --yes | boolean | false | Skip prompts, use defaults |
| -h, --help | - | - | Show help message |
| -v, --version | - | - | Show version number |

$3

The --components flag controls which UI components are included:

`bash


Include all components (default with -y)

--components
--components=all

Exclude all optional components

--components=none

Include specific categories

--components=ui
--components=ui,patterns
--components=ui,patterns,hero
`

Component Categories:

| Category | Components | Count |
|----------|------------|-------|
| ui | Button, Input, Card, Badge, Alert, Dialog, Tabs, Select, Checkbox, Radio, Textarea, Tooltip, Dropdown, Skeleton, Logo, CodeBlock, SocialProof, Avatar, TerminalDemo, VerticalTabs, CTA | 21 |
| patterns | ContactForm, NewsletterForm, FormField | 3 |
| hero | Hero (flexible hero section) | 1 |

Component Features

$3

Flexible navigation header with variant-based configuration:

`astro
layout="default"
position="sticky"
size="md"
variant="default"
colorScheme="default"
showCta={true}
showThemeToggle={true}
showLanguageSwitcher={true}
/>
`

$3

Four layout variants for different site needs:

`astro
layout="simple"
background="default"
columns={3}
showSocial={true}
showCopyright={true}
socialLinks={[{ platform: 'github', href: '...' }]}
legalLinks={[{ label: 'Privacy', href: '/privacy' }]}
/>
`

$3

Flexible hero section with multiple layout options:

`astro
layout="single"
splitRatio="1:1"
align="left"
background="default"
size="lg"
showGrid={true}
showBlob={true}
title="Your Title"
titleHighlight="Title"
description="..."
/>
`

$3

Reusable call-to-action section:

`astro
variant="default"
size="lg"
align="center"
showLogo={true}
heading="Ready to start?"
headingHighlight="start"
description="Get started in seconds."
showCopyCommand={true}
/>
`

$3

Production-ready button with variants:

`astro
variant="primary"
size="md"
colorScheme="default"
fullWidth={false}
icon={false}
href="/path"
/>
`

Examples

$3

`bash
npm create velocity-astro@latest my-site -y --demo=false --components=none
`

Creates a clean starter with just layouts, SEO components, and basic pages.

$3

`bash
npm create velocity-astro@latest my-site --demo --components --i18n
`

Includes everything: demo landing page, all components, and i18n support.

$3

`bash
npm create velocity-astro@latest client-site --demo --components=ui,patterns
`

Demo content to customize, plus UI and form components for building pages.

$3

`bash
npm create velocity-astro@latest global-site --i18n --demo
`

Full i18n support with:
- Locale-prefixed routes (/en/, /es/, /fr/)
- Language switcher component
- Translated navigation and content
- SEO hreflang tags

$3

`bash
npm create velocity-astro@latest my-site --pages
`

Interactive prompt to generate starter pages (services, pricing, team, etc.).

How It Works

$3

`
User runs CLI
│
▼
Downloads FULL Velocity repo from GitHub (via giget)
│
▼
Applies local template overlays (i18n, base)
│
▼
Configures based on CLI options
│
▼
Installs dependencies
`

The CLI downloads the complete Velocity repository at runtime, then applies configuration overlays based on your selections. This means you always get the latest Velocity features.

$3

1. Download template - Fetches Velocity from GitHub via giget
2. Configure components - Filters to selected component categories
3. Apply i18n overlay - Adds internationalization if enabled
4. Remove demo content - Strips demo pages if --demo=false
5. Generate pages - Creates starter pages if requested
6. Update package.json - Sets project name and cleans metadata
7. Initialize git - Creates git repository with initial commit
8. Install dependencies - Runs package manager install

$3

The CLI uses a template overlay approach:

- Base Velocity: Downloaded from GitHub (always fresh)
- i18n overlay: Adds locale routing, translations, language switcher
- Base template: Minimal pages for non-demo projects

Overlays are applied in order, with later files overwriting earlier ones.

$3

Components are managed via component-registry.json in Velocity. The registry defines:

- Component files and locations
- Dependencies between components
- Required utilities (like cn for class merging)
- Category groupings

When you select categories, the CLI resolves all dependencies automatically.

What's Included

Every Velocity project includes:

| Feature | Description |
|---------|-------------|
| Astro 6 | Latest Astro with View Transitions |
| Tailwind CSS v4 | Modern utility-first CSS with native cascade layers |
| TypeScript | Full type safety throughout |
| React | For interactive islands and components |
| MDX | Write content with JSX components |
| SEO | Meta tags, Open Graph, JSON-LD schemas |
| Sitemap | Auto-generated sitemap.xml |
| RSS Feed | Built-in RSS support |
| Dark Mode | System-aware theme switching |
| ESLint + Prettier | Code quality and formatting |
| Analytics Ready | GA4 and GTM support via env vars |

$3

| Feature | Flag | Description |
|---------|------|-------------|
| Demo content | --demo | Landing page, sample blog posts, about/contact pages |
| UI Components | --components | 27+ production-ready components |
| i18n Support | --i18n | Multi-language routing and translations |
| Starter Pages | --pages | Generate custom pages interactively |

Configuration

$3

Create a .env file to configure analytics and verification:

`env


Analytics (optional)

PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
PUBLIC_GTM_ID=GTM-XXXXXXX

Site Verification (optional)

GOOGLE_SITE_VERIFICATION=your-verification-code
BING_SITE_VERIFICATION=your-verification-code

Site URL (required for production)

SITE_URL=https://your-domain.com
`

$3

Edit src/config/site.config.ts to customize:

`typescript
const siteConfig: SiteConfig = {
name: 'Your Site Name',
description: 'Your site description',
url: 'https://your-domain.com',
author: 'Your Name',
email: 'hello@example.com',

// Branding
branding: {
logo: { alt: 'Your Logo' },
favicon: { svg: '/favicon.svg' },
colors: {
themeColor: '#F94C10',
backgroundColor: '#ffffff',
},
},
};
`

$3

Replace these files with your own branding:

- public/favicon.svg - Site favicon
- src/assets/branding/ - Logo SVG files

Development

After scaffolding, run:

`bash
cd my-site
npm run dev # Start dev server at localhost:4321
npm run build # Build for production
npm run preview # Preview production build
`

Deployment

Velocity includes ready-to-use configurations for:

- Vercel - Zero-config deployment
- Netlify - Includes netlify.toml
- Cloudflare Pages - SSR-ready

Troubleshooting

$3

If template download fails:
- Check your internet connection
- Verify GitHub is accessible
- Try again in a few minutes

$3

The CLI will prompt to overwrite existing directories. Use a new directory name or clear the existing one.

$3

On Unix systems, you may need to set execute permissions:

`bash
chmod +x node_modules/.bin/create-velocity-astro
`

$3

If automatic installation fails:

`bash
cd my-site
npm install # or pnpm install / yarn
``

Requirements

- Node.js 18.0.0 or higher
- Package Manager: npm, pnpm, yarn, or bun
- Git (optional, for repository initialization)

Related

- Velocity - The Astro starter kit
- Astro - The web framework
- Tailwind CSS - The CSS framework

License

MIT - Southwell Media