create-velocity-astro 1.3.0 → 1.4.1

package/README.md

@@ -1,16 +1,16 @@
 # create-velocity-astro
 
-Scaffold production-ready [Velocity](https://github.com/southwellmedia-dev/velocity) projects in seconds.
+Scaffold production-ready [Velocity](https://github.com/southwellmedia/velocity) projects in seconds.
 
-Velocity is an opinionated Astro 6 + Tailwind CSS v4 starter kit used by Southwell Media to deliver production client sites.
+Velocity is an opinionated Astro 6 + Tailwind CSS v4 starter kit with 27+ components, i18n support, SEO optimization, and deployment-ready configuration.
 
-## Usage
+## Quick Start
 
 ```bash
 # npm
 npm create velocity-astro@latest my-site
 
-# pnpm
+# pnpm (recommended)
 pnpm create velocity-astro my-site
 
 # yarn
@@ -20,85 +20,282 @@ yarn create velocity-astro my-site
 bun create velocity-astro my-site
 ```
 
-## Options
+## CLI Options
 
-| Flag | Description |
-|------|-------------|
-| `--demo` | Include demo landing page and sample content |
-| `--components` | Include UI component library (buttons, forms, cards, etc.) |
-| `--i18n` | Add internationalization support with locale routing |
-| `--yes`, `-y` | Skip prompts and use default options |
-| `--help`, `-h` | Show help message |
-| `--version`, `-v` | Show version number |
+| 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 |
+
+### Component Selection
+
+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 |
 
 ## Examples
 
-### Create a minimal project
+### Minimal Project (fastest)
 
 ```bash
-npm create velocity-astro@latest my-site
+npm create velocity-astro@latest my-site -y --demo=false --components=none
 ```
 
-This gives you a clean starter with:
-- Basic index, blog, and 404 pages
-- Layouts and configuration
-- SEO components
-- Tailwind CSS v4 setup
+Creates a clean starter with just layouts, SEO components, and basic pages.
 
-### Create a project with demo content
+### Full-Featured Project
 
 ```bash
-npm create velocity-astro@latest my-site --demo
+npm create velocity-astro@latest my-site --demo --components --i18n
 ```
 
-Includes the full demo landing page with:
-- Hero, features, CTA sections
-- Sample blog posts
-- About and contact pages
+Includes everything: demo landing page, all components, and i18n support.
 
-### Include the UI component library
+### Production Site Setup
 
 ```bash
-npm create velocity-astro@latest my-site --components
+npm create velocity-astro@latest client-site --demo --components=ui,patterns
 ```
 
-Adds 27+ production-ready components:
-- Button, Input, Textarea, Select, Checkbox, Radio
-- Card, Alert, Badge, Avatar, Skeleton
-- Dialog, Dropdown, Tabs, Tooltip
-- And more...
+Demo content to customize, plus UI and form components for building pages.
 
-### Full-featured project
+### i18n Multi-Language Site
 
 ```bash
-npm create velocity-astro@latest my-site --demo --components --i18n
+npm create velocity-astro@latest global-site --i18n --demo
 ```
 
-### Skip prompts with defaults
+Full i18n support with:
+- Locale-prefixed routes (`/en/`, `/es/`, `/fr/`)
+- Language switcher component
+- Translated navigation and content
+- SEO hreflang tags
+
+### Custom Pages Generation
 
 ```bash
-npm create velocity-astro@latest my-site -y
+npm create velocity-astro@latest my-site --pages
+```
+
+Interactive prompt to generate starter pages (services, pricing, team, etc.).
+
+## How It Works
+
+### Architecture
+
 ```
+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](https://github.com/southwellmedia/velocity) at runtime, then applies configuration overlays based on your selections. This means you always get the latest Velocity features.
+
+### 8-Step Scaffolding Process
+
+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
+
+### Template Overlay System
+
+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.
+
+### Component Registry
+
+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 comes with:
+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 |
+
+### Optional Features
+
+| 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
+
+### Environment Variables
+
+Create a `.env` file to configure analytics and verification:
 
-- **Astro 6** - The web framework for content-driven websites
-- **Tailwind CSS v4** - Utility-first CSS framework
-- **TypeScript** - Type safety out of the box
-- **React** - For interactive islands
-- **MDX** - Write content with JSX components
-- **SEO** - Meta tags, Open Graph, JSON-LD schemas
-- **Sitemap** - Auto-generated sitemap.xml
-- **ESLint + Prettier** - Code quality and formatting
-- **Deployment configs** - Vercel, Netlify, Cloudflare ready
+```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
+```
+
+### Site Configuration
+
+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',
+    },
+  },
+};
+```
+
+### Branding Files
+
+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
+
+### Network Errors
+
+If template download fails:
+- Check your internet connection
+- Verify GitHub is accessible
+- Try again in a few minutes
+
+### Directory Already Exists
+
+The CLI will prompt to overwrite existing directories. Use a new directory name or clear the existing one.
+
+### Permission Errors
+
+On Unix systems, you may need to set execute permissions:
+
+```bash
+chmod +x node_modules/.bin/create-velocity-astro
+```
+
+### Dependency Installation Fails
+
+If automatic installation fails:
+
+```bash
+cd my-site
+npm install  # or pnpm install / yarn
+```
 
 ## Requirements
 
-- Node.js 18.0.0 or higher
-- pnpm, npm, yarn, or bun
+- **Node.js** 18.0.0 or higher
+- **Package Manager**: npm, pnpm, yarn, or bun
+- **Git** (optional, for repository initialization)
+
+## Related
+
+- [Velocity](https://github.com/southwellmedia/velocity) - The Astro starter kit
+- [Astro](https://astro.build) - The web framework
+- [Tailwind CSS](https://tailwindcss.com) - The CSS framework
 
 ## License
 
-MIT - Southwell Media
+MIT - [Southwell Media](https://southwellmedia.com)