bsmnt 0.0.2 → 0.1.1

package/packages/create-basement-app/templates/webgl/.editorconfig

@@ -0,0 +1,40 @@
+# EditorConfig helps maintain consistent coding styles across different editors
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.{css,scss}]
+indent_size = 2
+
+[*.{ts,tsx,js,jsx,mjs}]
+indent_size = 2
+
+[*.svg]
+insert_final_newline = false
+
+[{package.json,package-lock.json,bun.lockb}]
+indent_size = 2
+
+[.env*]
+insert_final_newline = true
+

package/packages/create-basement-app/templates/webgl/.env.example

@@ -0,0 +1,81 @@
+# ============================================
+# Basement Next Starter - Environment Variables
+# ============================================
+# Copy this file to .env.local and fill in the values
+# Run: cp .env.example .env.local
+#
+# Only configure the integrations you need.
+# Remove unused sections to keep your env file clean.
+# ============================================
+
+
+# ============================================
+# CORE (Recommended)
+# ============================================
+
+# Base URL for your site (used for SEO, canonical URLs, etc.)
+# Development: http://localhost:3000
+# Production: https://your-domain.com
+NEXT_PUBLIC_BASE_URL="http://localhost:3000"
+
+# Draft mode secret for preview functionality
+# Generate a random string: openssl rand -base64 32
+DRAFT_MODE_TOKEN=""
+
+
+# ============================================
+# SANITY CMS (Optional)
+# Headless CMS with visual editing
+# Get credentials: https://sanity.io/manage
+# Docs: https://www.sanity.io/docs
+# ============================================
+
+# Required for Sanity
+NEXT_PUBLIC_SANITY_PROJECT_ID=""
+NEXT_PUBLIC_SANITY_DATASET="production"
+NEXT_PUBLIC_SANITY_API_READ_TOKEN=""
+
+# Optional - for server-side mutations and visual editing
+# SANITY_PRIVATE_TOKEN=""
+
+# Optional - API version (defaults to 2024-03-15)
+# NEXT_PUBLIC_SANITY_API_VERSION="2024-03-15"
+
+
+# ============================================
+# SHOPIFY (Optional)
+# E-commerce platform with cart and checkout
+# Get credentials: https://shopify.dev/docs/storefronts/headless
+# ============================================
+
+# Required for Shopify
+# SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
+# SHOPIFY_STOREFRONT_ACCESS_TOKEN=""
+
+# Optional - for revalidation webhooks
+# SHOPIFY_REVALIDATION_SECRET=""
+
+# Optional - for customer accounts
+# SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID=""
+# SHOPIFY_CUSTOMER_ACCOUNT_API_URL=""
+
+# ============================================
+# ANALYTICS (Optional)
+# ============================================
+
+# Google Analytics
+# NEXT_PUBLIC_GOOGLE_ANALYTICS=""
+
+# Google Tag Manager
+# NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID=""
+
+# Facebook
+# NEXT_PUBLIC_FACEBOOK_APP_ID=""
+
+
+# ============================================
+# VERCEL (Auto-populated by Vercel CLI)
+# ============================================
+
+# These are automatically set by Vercel
+# VERCEL_OIDC_TOKEN=""

package/packages/create-basement-app/templates/webgl/.gitattributes

@@ -0,0 +1,19 @@
+# Git Attributes Configuration
+# This file ensures consistent line endings across all platforms
+#
+# Configuration:
+#   *           - Applies to all files in the repository
+#   text=auto   - Git automatically detects text vs binary files
+#   eol=lf      - Normalizes line endings to LF (Unix-style) for text files
+#
+# Why this matters:
+#   - Windows uses CRLF (\r\n) line endings
+#   - Unix/Linux/macOS use LF (\n) line endings
+#   - This prevents line-ending conflicts and ensures consistent diffs
+#
+# What it does:
+#   - On commit: Normalizes all text files to LF line endings
+#   - On checkout: Converts to platform-native format if needed
+#   - Prevents merge conflicts caused by line ending differences
+
+* text=auto eol=lf

package/packages/create-basement-app/templates/webgl/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] `bun lint` passes
+- [ ] Tested locally in dev mode
+- [ ] No breaking changes (or documented in summary)
+

package/packages/create-basement-app/templates/webgl/.github/workflows/lighthouse-to-slack.yml

@@ -0,0 +1,136 @@
+# Lighthouse Performance Reports
+#
+# Runs Lighthouse on Vercel deployments and posts results as commit comments.
+# Our GitHub → Slack integration forwards these to Slack automatically.
+#
+# Required GitHub Secrets:
+#   VERCEL_TOKEN - Vercel API token (Settings → Tokens)
+
+name: Lighthouse
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize]
+    branches: [main]
+    paths:
+      # Only runs when relevant files change
+      - 'app/**'
+      - 'components/**'
+      - 'lib/**'
+      - 'public/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'next.config.**'
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: read
+
+jobs:
+  lighthouse:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Discover Vercel Project
+        id: vercel_info
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+        run: |
+          project_name="${GITHUB_REPOSITORY##*/}"
+          echo "Looking for Vercel project: $project_name"
+
+          # Get team ID for basement.studio
+          teams=$(curl -s -H "Authorization: Bearer $VERCEL_TOKEN" "https://api.vercel.com/v2/teams")
+          team_id=$(echo "$teams" | jq -r '.teams[] | select(.slug=="basement") | .id')
+          echo "Team ID: $team_id"
+
+          # Get project ID by matching repo name
+          projects=$(curl -s -H "Authorization: Bearer $VERCEL_TOKEN" "https://api.vercel.com/v9/projects?teamId=$team_id")
+          project_id=$(echo "$projects" | jq -r ".projects[] | select(.name==\"$project_name\") | .id")
+          echo "Project ID: $project_id"
+
+          echo "team_id=$team_id" >> $GITHUB_OUTPUT
+          echo "project_id=$project_id" >> $GITHUB_OUTPUT
+
+      - name: Get Vercel Preview URL
+        id: vercel_url
+        uses: zentered/vercel-preview-url@v1.4.0
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+        with:
+          vercel_team_id: ${{ steps.vercel_info.outputs.team_id }}
+          vercel_project_id: ${{ steps.vercel_info.outputs.project_id }}
+
+      - name: Wait for Deployment
+        id: await
+        uses: UnlyEd/github-action-await-vercel@v2.0.0
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+        with:
+          deployment-url: ${{ steps.vercel_url.outputs.preview_url }}
+          timeout: 300
+          poll-interval: 10
+        continue-on-error: true
+
+      - name: Run Lighthouse
+        if: steps.await.outcome == 'success'
+        id: lighthouse
+        uses: treosh/lighthouse-ci-action@v12
+        env:
+          LHCI_BUILD_CONTEXT__CURRENT_HASH: ${{ github.sha }}
+        with:
+          urls: https://${{ steps.vercel_url.outputs.preview_url }}
+          uploadArtifacts: true
+          temporaryPublicStorage: true
+
+      - name: Format Results
+        id: format
+        uses: actions/github-script@v8
+        env:
+          DEPLOYMENT_FAILED: ${{ steps.await.outcome != 'success' }}
+          PREVIEW_URL: ${{ steps.vercel_url.outputs.preview_url }}
+          MANIFEST: ${{ steps.lighthouse.outputs.manifest }}
+          LINKS: ${{ steps.lighthouse.outputs.links }}
+        with:
+          script: |
+            if (process.env.DEPLOYMENT_FAILED === 'true') {
+              core.setOutput('comment', '⚠️ Vercel deployment failed or timed out. Lighthouse audit skipped.');
+              return;
+            }
+
+            try {
+              const manifest = JSON.parse(process.env.MANIFEST);
+              const links = JSON.parse(process.env.LINKS);
+              const previewUrl = process.env.PREVIEW_URL;
+
+              const scores = manifest[0].summary;
+              const reportUrl = Object.values(links)[0];
+
+              const emoji = (score) => score >= 0.9 ? '🟢' : score >= 0.5 ? '🟠' : '🔴';
+              const format = (score) => Math.round(score * 100);
+
+              const comment = [
+                `⚡️ [Lighthouse report](${reportUrl}) for this commit:`,
+                '',
+                `${emoji(scores.performance)} Performance: ${format(scores.performance)}`,
+                `${emoji(scores.accessibility)} Accessibility: ${format(scores.accessibility)}`,
+                `${emoji(scores['best-practices'])} Best Practices: ${format(scores['best-practices'])}`,
+                `${emoji(scores.seo)} SEO: ${format(scores.seo)}`,
+                '',
+                `*Tested on [${previewUrl}](https://${previewUrl})*`
+              ].join('\n');
+
+              core.setOutput('comment', comment);
+            } catch (error) {
+              console.error('Error:', error);
+              core.setOutput('comment', '⚠️ Failed to generate Lighthouse report. Check workflow logs.');
+            }
+
+      - name: Post Commit Comment
+        uses: peter-evans/commit-comment@v4
+        with:
+          body: ${{ steps.format.outputs.comment }}

package/packages/create-basement-app/templates/webgl/.vscode/extensions.json

@@ -0,0 +1,20 @@
+{
+  "recommendations": [
+    // Formatting & Linting
+    "biomejs.biome",
+
+    // CSS & Styling
+    "bradlc.vscode-tailwindcss",
+    "csstools.postcss",
+
+    // GraphQL (Shopify, etc.)
+    "graphql.vscode-graphql-syntax",
+
+    // Sanity CMS (GROQ syntax + validation)
+    "sanity-io.vscode-sanity",
+
+    // DX Enhancements
+    "yoavbls.pretty-ts-errors",
+    "waderyan.gitblame"
+  ]
+}

package/packages/create-basement-app/templates/webgl/.vscode/settings.json

@@ -0,0 +1,105 @@
+{
+  // Language-specific formatters (explicit per-language ensures no fallback to other formatters)
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[postcss]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "colorize.languages": [
+    "javascript",
+    "typescript",
+    "css",
+    "scss",
+    "less",
+    "html",
+    "json",
+    "yaml",
+    "markdown",
+    "glsl"
+  ],
+  "css.lint.unknownAtRules": "ignore",
+
+  // CSS (Tailwind v4)
+  "css.lint.validProperties": ["user-drag"],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "always",
+    "source.organizeImports.biome": "always"
+  },
+  "editor.defaultFormatter": "biomejs.biome",
+
+  // Formatting
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+
+  // File associations
+  "files.associations": {
+    "*.css": "css",
+    "*.json": "jsonc"
+  },
+
+  // General
+  "files.eol": "\n",
+  // "typescript.experimental.useTsgo": true, // Disabled: tsgo doesn't support Next.js plugin
+  "javascript.suggest.autoImports": true,
+  // Disable Prettier to prevent silent formatter conflicts
+  "prettier.enable": false,
+
+  // Search exclusions (performance)
+  "search.exclude": {
+    "**/.next": true,
+    "**/.vercel": true,
+    "**/bun.lock": true,
+    "**/lib/integrations/sanity/sanity.types.ts": true,
+    "**/node_modules": true
+  },
+  "tailwindCSS.classAttributes": [
+    "class",
+    "className",
+    ".*ClassName",
+    ".*Styles"
+  ],
+  "tailwindCSS.classFunctions": ["cn", "cva", "twMerge", "cx"],
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^\"'`]*)(?:'|\"|`)"],
+    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
+  ],
+  "tailwindCSS.experimental.configFile": "./lib/styles/css/tailwind.css",
+  "tailwindCSS.includeLanguages": {
+    "typescriptreact": "html"
+  },
+  "typescript.preferences.importModuleSpecifier": "non-relative",
+
+  // TypeScript
+  "typescript.suggest.autoImports": true,
+  "typescript.tsdk": "node_modules/typescript/lib",
+
+  // Editor labels (fixed for .tsx files)
+  "workbench.editor.customLabels.patterns": {
+    "**/app/**/layout.tsx": "${dirname(1)}/${dirname} <layout>",
+    "**/app/**/page.tsx": "${dirname(1)}/${dirname} <page>",
+    "**/app/api/**/route.ts": "${dirname(1)}/${dirname} <route>",
+    "**/components/**/index.tsx": "${dirname} <component>"
+  },
+  "workbench.editorAssociations": {
+    "*.svg": "default"
+  }
+}

package/packages/create-basement-app/templates/webgl/README.md

@@ -0,0 +1,221 @@
+# Basement Next Starter
+
+A production-ready Next.js starter with React 19, Tailwind CSS v4, TypeScript strict mode, and everything you need to build modern web applications.
+
+## Tech Stack
+
+| Technology | Version | Description |
+|------------|---------|-------------|
+| Next.js | 16.1 | App Router, Turbopack |
+| React | 19 | React Compiler enabled |
+| TypeScript | 5.9 | Strict mode, `noUncheckedIndexedAccess` |
+| Tailwind CSS | 4 | CSS-first configuration |
+| Biome | 2.3 | Linting and formatting |
+| Bun | 1.3 | Package manager and runtime |
+| Zustand | 5.0 | State management |
+
+## Quick Start
+
+```bash
+# Clone the template
+bunx degit basementstudio/next-starter my-project
+
+# Install dependencies
+cd my-project && bun install
+
+# Start development
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the result.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun dev` | Start development server with Turbopack |
+| `bun dev:https` | Start with HTTPS (for secure contexts) |
+| `bun build` | Build for production |
+| `bun start` | Start production server |
+| `bun generate` | Scaffold new components/hooks |
+| `bun lint` | Run Biome linter |
+| `bun lint:fix` | Fix lint issues |
+| `bun format` | Format code with Biome |
+| `bun typecheck` | Type check with tsgo |
+| `bun test` | Run tests with Bun |
+| `bun analyze` | Analyze bundle size |
+
+## Project Structure
+
+```
+app/                     # Next.js App Router pages and routes
+  ├── api/               # API routes (draft-mode, revalidate)
+  ├── layout.tsx         # Root layout with metadata, fonts
+  ├── page.tsx           # Homepage
+  ├── sitemap.ts         # Dynamic sitemap generation
+  └── robots.ts          # SEO robots.txt
+
+components/
+  ├── layout/
+  │   ├── header/        # Navigation header
+  │   ├── footer/        # Page footer
+  │   ├── wrapper/       # Page wrapper with theme
+  │   └── theme/         # Theme context provider
+  └── ui/
+      ├── image/         # Enhanced Next.js Image wrapper
+      └── link/          # Smart Link component
+
+lib/
+  ├── hooks/                      # Custom React hooks
+  │   ├── use-device-detection/   # Device/capability detection
+  │   ├── use-media-breakpoint/   # Responsive breakpoint hook
+  │   └── use-prefetch/           # Prefetch utilities
+  ├── integrations/               # Third-party integrations
+  ├── scripts/                    # Build and dev scripts
+  ├── store/                      # Zustand global state
+  ├── styles/                     # Design tokens, CSS config
+  │   ├── colors.ts               # Theme colors
+  │   ├── layout.mjs              # Breakpoints, grid, spacing
+  │   ├── easings.ts              # CSS easing variables
+  │   └── fonts.ts                # Font loading (Geist Mono)
+  └── utils/                      # Utility functions
+      ├── easings.ts              # 30+ animation easing functions
+      ├── math.ts                 # Math utilities
+      ├── strings.ts              # String utilities
+      └── fetch.ts                # Fetch utilities
+```
+
+## Features
+
+### Design System
+
+Pre-configured design tokens ready to use:
+
+**Breakpoints:**
+- `mobile`: 375px
+- `tablet`: 620px
+- `tablet-lg`: 1024px
+- `desktop`: 1440px
+- `desktop-large`: 1920px
+
+**Grid:**
+- Mobile: 4 columns
+- Desktop: 12 columns
+- Gap: 16px
+
+**Colors:**
+- Theme colors: `primary`, `secondary`, `contrast`
+- Accent colors: `red`, `blue`, `green`, `violet`, `pink`
+- Light/dark mode support
+
+**Easings:**
+30+ easing functions (quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce)
+
+### Smart Components
+
+**`<Image>`** - Enhanced Next.js Image wrapper:
+- Automatic responsive sizes based on breakpoints
+- Blur placeholder with shimmer effect
+- Preload support for LCP images
+- SVG handling
+
+**`<Link>`** - Intelligent link component:
+- Auto-detects external links (opens in new tab)
+- Connection-aware prefetching (4G only, respects data saver)
+- Falls back to button/div when no href
+- Active state detection
+
+**`<Wrapper>`** - Page layout component:
+- Includes Header and Footer
+- Theme provider integration
+- Flexible content area
+
+### Theme Support
+
+Light/dark theme with CSS custom properties:
+
+```tsx
+import { Wrapper } from "@/components/layout/wrapper"
+
+export default function Page() {
+  return (
+    <Wrapper theme="dark">
+      <section>Your content</section>
+    </Wrapper>
+  )
+}
+```
+
+Access theme in components:
+
+```tsx
+import { useTheme } from "@/components/layout/theme"
+
+function Component() {
+  const { name, setThemeName } = useTheme()
+  // ...
+}
+```
+
+### Performance Optimizations
+
+- **React Compiler** - Automatic memoization (no manual `useMemo`/`useCallback`)
+- **Turbopack** - Fast development builds
+- **Bundle Analyzer** - `bun analyze` to inspect bundle size
+- **Optimized Imports** - Auto-optimization for GSAP, Three.js, Lenis, Zustand
+- **Security Headers** - CSP, HSTS, XSS protection pre-configured
+- **Image Optimization** - AVIF, WebP with custom quality settings
+
+### Developer Experience
+
+- **Component Scaffolding** - `bun generate` to create components/hooks
+- **HTTPS Dev Server** - `bun dev:https` for secure contexts
+- **Strict TypeScript** - `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
+- **Biome** - Fast linting and formatting with custom rules
+- **Tests** - Bun test runner with utilities
+
+## Configuration
+
+### Styles
+
+Edit design tokens in `lib/styles/`:
+
+- `colors.ts` - Theme and accent colors
+- `layout.mjs` - Breakpoints, grid, spacing
+- `typography.ts` - Font definitions
+- `easings.ts` - CSS easing variables
+
+After editing, regenerate CSS:
+
+```bash
+bun setup:styles
+```
+
+### Next.js
+
+Configuration in `next.config.ts`:
+
+- React Compiler enabled
+- Typed routes
+- SVG loader (@svgr/webpack)
+- Security headers
+- Image optimization settings
+
+## Deployment
+
+### Vercel (Recommended)
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/basementstudio/next-starter)
+
+### Other Platforms
+
+```bash
+bun build
+bun start
+```
+
+The app runs on port 3000 by default.
+
+## License
+
+MIT