bsmnt 0.2.0 → 0.2.5

package/README.md

@@ -1,4 +1,4 @@
-# bsmnt `1.0.0`
+# bsmnt `0.2.5`
 
 Your project starts here. One command to go from zero to a fully configured Next.js project with our stack, CMS, agent skills, and everything wired up.
 

package/package.json

@@ -1,17 +1,24 @@
 {
 	"name": "bsmnt",
-	"version": "0.2.0",
+	"version": "0.2.5",
 	"packageManager": "bun@1.2.20",
 	"description": "CLI to scaffold basement projects and add integrations",
 	"type": "module",
+	"workspaces": [
+		".",
+		"src/templates/*"
+	],
 	"bin": {
-		"bsmnt": "./index.js"
+		"bsmnt": "index.js"
 	},
 	"main": "./dist/index.js",
 	"files": [
 		"dist",
 		"index.js",
 		"src/templates",
+		"!src/templates/*/node_modules",
+		"!src/templates/*/.next",
+		"!src/templates/*/bun.lock",
 		"src/template-hooks",
 		"plugins"
 	],
@@ -22,10 +29,20 @@
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"changeset": "changeset",
-		"version-packages": "changeset version",
+		"version-packages": "changeset version && node scripts/sync-readme-version.js",
 		"release": "changeset publish",
-		"prepublishOnly": "bun run build",
-		"default": "turbo run dev --filter=basement-next-starter"
+		"prepublishOnly": "rm -rf dist && bun run build",
+		"default": "turbo run dev --filter=bsmnt-next-starter",
+		"webgpu": "turbo run dev --filter=bsmnt-webgpu-starter",
+		"experiments": "turbo run dev --filter=bsmnt-experiments-starter",
+		"build:default": "turbo run build --filter=bsmnt-next-starter",
+		"build:webgpu": "turbo run build --filter=bsmnt-webgpu-starter",
+		"build:experiments": "turbo run build --filter=bsmnt-experiments-starter",
+		"build:all": "turbo run build --filter=bsmnt-next-starter --filter=bsmnt-webgpu-starter --filter=bsmnt-experiments-starter",
+		"lint:default": "turbo run lint --filter=bsmnt-next-starter",
+		"lint:webgpu": "turbo run lint --filter=bsmnt-webgpu-starter",
+		"lint:experiments": "turbo run lint --filter=bsmnt-experiments-starter",
+		"lint:all": "turbo run lint --filter=bsmnt-next-starter --filter=bsmnt-webgpu-starter --filter=bsmnt-experiments-starter"
 	},
 	"keywords": [
 		"webgpu",

package/src/templates/next-default/.biome/plugins/no-anchor-element.grit

@@ -0,0 +1,12 @@
+language js;
+
+`<a $attrs>$content</a>` as $anchor where {
+    !$anchor <: within `if ($condition) { return ($jsx) }` where {
+        $condition <: contains or { `isExternal`, `isExternalSSR` }
+    },
+    register_diagnostic(
+        span = $anchor,
+        message = "Use custom Link component instead of <a> element. The Link component handles both internal and external links automatically.",
+        severity = "error"
+    )
+} 

package/src/templates/next-default/.biome/plugins/no-relative-parent-imports.grit

@@ -0,0 +1,10 @@
+language js;
+
+`import $imports from $source` as $import where {
+    $source <: r"['\"]\.\.\/\.\.\/.*['\"]",
+    register_diagnostic(
+        span = $import,
+        message = "Use alias imports (~/dir/) instead of deep relative imports (../../). Single level imports (../) are allowed for colocated files.",
+        severity = "error"
+    )
+} 

package/src/templates/next-default/.biome/plugins/no-unnecessary-forwardref.grit

@@ -0,0 +1,9 @@
+language js;
+
+`forwardRef($func)` as $ref where {
+    register_diagnostic(
+        span = $ref,
+        message = "forwardRef is unnecessary in React 19 with the compiler",
+        severity = "warning"
+    )
+} 

package/src/templates/next-default/.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/src/templates/next-default/.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/src/templates/next-default/.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/src/templates/next-default/app/layout.tsx

@@ -0,0 +1,104 @@
+import type { Metadata, Viewport } from "next";
+import { Geist } from "next/font/google";
+import { type PropsWithChildren, Suspense } from "react";
+import { Link } from "@/components/ui/link";
+import { themes } from "@/lib/styles/colors";
+import { fontsVariable } from "@/lib/styles/fonts";
+import AppData from "@/package.json";
+import "@/lib/styles/css/index.css";
+import { cn } from "@/lib/styles/cn";
+
+const APP_NAME = AppData.name;
+const APP_DEFAULT_TITLE = "Basement Starter";
+const APP_TITLE_TEMPLATE = "%s - Basement Starter";
+const APP_DESCRIPTION = AppData.description;
+const APP_BASE_URL =
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+
+const geist = Geist({
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  alternates: {
+    canonical: "/",
+    languages: {
+      "en-US": "/en-US",
+    },
+  },
+  appleWebApp: {
+    capable: true,
+    statusBarStyle: "default",
+    title: APP_DEFAULT_TITLE,
+  },
+  applicationName: APP_NAME,
+  authors: [{ name: "basement.studio", url: "https://basement.studio" }],
+  description: APP_DESCRIPTION,
+  formatDetection: { telephone: false },
+  metadataBase: new URL(APP_BASE_URL),
+  openGraph: {
+    description: APP_DESCRIPTION,
+    images: [
+      {
+        alt: APP_DEFAULT_TITLE,
+        height: 630,
+        url: "/opengraph-image.jpg",
+        width: 1200,
+      },
+    ],
+    locale: "en_US",
+    siteName: APP_NAME,
+    title: {
+      default: APP_DEFAULT_TITLE,
+      template: APP_TITLE_TEMPLATE,
+    },
+    type: "website",
+    url: APP_BASE_URL,
+  },
+  other: {
+    "fb:app_id": process.env.NEXT_PUBLIC_FACEBOOK_APP_ID || "",
+  },
+  title: {
+    default: APP_DEFAULT_TITLE,
+    template: APP_TITLE_TEMPLATE,
+  },
+  twitter: {
+    card: "summary_large_image",
+    description: APP_DESCRIPTION,
+    title: {
+      default: APP_DEFAULT_TITLE,
+      template: APP_TITLE_TEMPLATE,
+    },
+  },
+};
+
+export const viewport: Viewport = {
+  colorScheme: "normal",
+  themeColor: themes.dark.primary,
+};
+
+export default async function Layout({ children }: PropsWithChildren) {
+  return (
+    <html
+      lang="en"
+      dir="ltr"
+      className={cn(fontsVariable, geist.className)}
+      // NOTE: This is due to the data-theme attribute being set which causes hydration errors
+      suppressHydrationWarning
+    >
+      <body>
+        {/* Skip link for keyboard navigation accessibility */}
+        <Suspense fallback={null}>
+          <Link
+            href="#main-content"
+            className="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-9999 focus:rounded focus:bg-black focus:px-4 focus:py-2 focus:text-white focus:outline-none focus:ring-2 focus:ring-white"
+          >
+            Skip to main content
+          </Link>
+        </Suspense>
+
+        {children}
+      </body>
+    </html>
+  );
+}

package/src/templates/next-default/app/page.tsx

@@ -0,0 +1,11 @@
+import { Wrapper } from "@/components/layout/wrapper"
+
+export default function Home() {
+  return (
+    <Wrapper theme="dark">
+      <section className="flex grow items-center justify-center">
+        <h1 className="font-mono text-xl uppercase">Basement Next Starter</h1>
+      </section>
+    </Wrapper>
+  )
+}

package/src/templates/next-default/app/robots.ts

@@ -0,0 +1,15 @@
+import type { MetadataRoute } from "next";
+
+const APP_BASE_URL =
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: {
+      userAgent: "*",
+      allow: "/",
+      disallow: [],
+    },
+    sitemap: `${APP_BASE_URL}/sitemap.xml`,
+  };
+}

package/src/templates/next-default/app/sitemap.ts

@@ -0,0 +1,16 @@
+import type { MetadataRoute } from "next";
+
+const APP_BASE_URL =
+  process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const baseRoutes: MetadataRoute.Sitemap = [
+    {
+      url: APP_BASE_URL,
+      lastModified: new Date(),
+      changeFrequency: "daily",
+      priority: 1,
+    },
+  ];
+  return baseRoutes;
+}

package/src/templates/next-default/biome.json

@@ -1,5 +1,5 @@
 {
-  "root": false,
+  "root": true,
   "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
   "assist": {
     "actions": {
@@ -245,6 +245,6 @@
   "vcs": {
     "clientKind": "git",
     "enabled": true,
-    "useIgnoreFile": true
+    "useIgnoreFile": false
   }
 }

package/src/templates/next-default/components/layout/footer/index.tsx

@@ -0,0 +1,31 @@
+import Logo from "@/components/basement.svg"
+import { Link } from "@/components/ui/link"
+
+export function Footer() {
+  return (
+    <footer className="flex flex-col items-center justify-between p-safe font-mono uppercase 2xl:flex-row 2xl:items-end">
+      <Link
+        href="https://basement.studio/"
+        className="link"
+        aria-label="Basement Studio"
+      >
+        <Logo className="w-148 text-secondary" />
+      </Link>
+      <div>
+        <Link
+          href="https://github.com/basementstudio/next-starter/generate"
+          className="link"
+        >
+          use this template
+        </Link>
+        {" / "}
+        <Link
+          href="https://github.com/basementstudio/next-starter"
+          className="link"
+        >
+          github
+        </Link>
+      </div>
+    </footer>
+  )
+}

package/src/templates/next-default/components/layout/header/index.tsx

@@ -0,0 +1,9 @@
+export function Header() {
+  return (
+    <nav className="sticky top-0 z-2 flex flex-col font-mono uppercase">
+      <div className="inline-flex px-safe py-safe">
+        <div className="font-bold text-xl">Basement Next Starter</div>
+      </div>
+    </nav>
+  )
+}

package/src/templates/next-default/components/layout/theme/index.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { createContext, useContext, useEffect, useState } from "react"
+import type { Themes } from "@/lib/styles/colors"
+import { type ThemeName, themes } from "@/lib/styles/config"
+
+export const ThemeContext = createContext<{
+  name: ThemeName
+  theme: Themes[ThemeName]
+  setThemeName: (theme: ThemeName) => void
+}>({
+  name: "light",
+  theme: themes.light,
+  setThemeName: () => {
+    void 0
+  },
+})
+
+export function useTheme() {
+  return useContext(ThemeContext)
+}
+
+export function Theme({
+  children,
+  theme,
+  global,
+}: {
+  children: React.ReactNode
+  theme: ThemeName
+  global?: boolean
+}) {
+  const pathname = usePathname()
+
+  const [currentTheme, setCurrentTheme] = useState(theme)
+
+  useEffect(() => {
+    setCurrentTheme(theme)
+  }, [theme])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: we need to trigger on path change
+  useEffect(() => {
+    if (global) {
+      document.documentElement.setAttribute("data-theme", currentTheme)
+    }
+  }, [pathname, currentTheme, global])
+
+  return (
+    <>
+      {global && /^[a-z]+$/.test(currentTheme) && (
+        <script>
+          {`document.documentElement.setAttribute('data-theme', '${currentTheme}');`}
+        </script>
+      )}
+      <ThemeContext.Provider
+        value={{
+          name: currentTheme,
+          theme: themes[currentTheme],
+          setThemeName: setCurrentTheme,
+        }}
+      >
+        {children}
+      </ThemeContext.Provider>
+    </>
+  )
+}

package/src/templates/next-default/components/layout/wrapper/index.tsx

@@ -0,0 +1,63 @@
+/**
+ * Main page wrapper providing theme, smooth scrolling, and WebGL context.
+ *
+ * Customize the Header and Footer components for your project needs.
+ */
+import cn from "clsx"
+import { Footer } from "@/components/layout/footer"
+import { Header } from "@/components/layout/header"
+import { Theme } from "@/components/layout/theme"
+import type { ThemeName } from "@/lib/styles/config"
+
+/**
+ * Props for the Wrapper component.
+ */
+interface WrapperProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Theme to apply ('dark' | 'light'). Defaults to 'dark'. */
+  theme?: ThemeName
+}
+
+/**
+ * Main page wrapper component providing theme.
+ *
+ * This component serves as the root container for pages, automatically handling
+ * theme application and layout structure.
+ * It includes navigation and footer.
+ *
+ * @param props - Component props
+ * @param props.theme - Color theme to apply to the page
+ * @param props.children - Page content
+ * @param props.className - Additional CSS classes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with theme
+ * export default function Page() {
+ *   return (
+ *     <Wrapper theme="dark">
+ *       <section>My page content</section>
+ *     </Wrapper>
+ *   )
+ * }
+ * ```
+ */
+export function Wrapper({
+  children,
+  theme = "dark",
+  className,
+  ...props
+}: WrapperProps) {
+  return (
+    <Theme theme={theme} global>
+      <Header />
+      <main
+        id="main-content"
+        className={cn("relative flex grow flex-col", className)}
+        {...props}
+      >
+        {children}
+      </main>
+      <Footer />
+    </Theme>
+  )
+}

package/src/templates/next-default/components/ui/README.md

@@ -0,0 +1,77 @@
+# Components
+
+UI components organized by purpose.
+
+```
+components/
+├── ui/        → Primitives (reusable across projects)
+├── layout/    → Site chrome (customize per project)
+└── magic/   → Animation & visual enhancements
+```
+
+## Direct Imports (Recommended)
+
+```tsx
+// UI Components - import directly for better clarity
+import { Image } from '@/components/ui/image'
+import { Link } from '@/components/ui/link'
+
+// Layout Components
+import { Wrapper } from '@/components/layout/wrapper'
+import { Header } from '@/components/layout/header' 
+import { Footer } from '@/components/layout/footer'
+
+// Magic Components
+import { Marquee } from '@/components/magic/marquee'
+```
+
+## UI Components
+
+| Component | Purpose |
+|-----------|---------|
+| `image/` | Optimized images (always use this, never `next/image`) |
+| `link/` | Smart navigation (auto-detects external) |
+
+## Layout Components
+
+| Component | Purpose |
+|-----------|---------|
+| `wrapper/` | Page wrapper (theme, WebGL, Lenis) |
+| `header/` | Site header/navigation |
+| `footer/` | Site footer |
+| `lenis/` | Smooth scrolling |
+
+```tsx
+<Wrapper theme="dark" webgl lenis>
+  <section>Your content</section>
+</Wrapper>
+```
+
+## Effects Components
+
+| Component | Purpose |
+|-----------|---------|
+| `marquee/` | Infinite scrolling text |
+
+## Best Practices
+
+```tsx
+// ✅ Always use custom Image
+import { Image } from '@/components/ui/image'
+<Image src="/photo.jpg" alt="Photo" aspectRatio={16/9} />
+
+// ✅ Always use custom Link
+import { Link } from '@/components/ui/link'
+<Link href="/about">Internal</Link>
+<Link href="https://example.com">External</Link>
+
+// ✅ CSS Modules + Tailwind
+import s from './component.module.css'
+<div className={cn(s.wrapper, 'flex items-center')} />
+```
+
+## Related
+
+- [Image docs](ui/image/README.md)
+- [Real Viewport docs](ui/real-viewport/README.md)
+- [WebGL Components](../lib/webgl/README.md)