uniweb 0.2.15 → 0.2.17

package/README.md

@@ -31,13 +31,19 @@ my-project/
 │   │       └── 1-hero.md     # Section content
 │   ├── locales/              # i18n (mirrors pages/)
 │   │   └── es/
+│   ├── src/
+│   │   └── main.jsx          # 1-line entry point
+│   ├── vite.config.js        # 3-line config
 │   └── public/               # Static assets
 │
 └── foundation/               # Your components
-    └── src/
-        └── components/
-            └── Hero/
-                └── index.jsx
+    ├── src/
+    │   └── components/
+    │       └── Hero/
+    │           ├── index.jsx
+    │           └── meta.js
+    ├── vite.config.js        # 3-line config
+    └── dist/                 # Built output
 ```
 
 **Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
@@ -98,7 +104,24 @@ export function Hero({ content, params }) {
 
 Standard React. Standard Tailwind. The `{ content, params }` interface is only for *exposed* components—the ones content creators select in markdown frontmatter. Internal components (the majority of your codebase) use regular React props.
 
-No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files. The CLI handles the wiring.
+No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files. Configuration is minimal—both site and foundation use 3-line Vite configs:
+
+```javascript
+// site/vite.config.js
+import { defineSiteConfig } from '@uniweb/build/site'
+export default defineSiteConfig()
+
+// foundation/vite.config.js
+import { defineFoundationConfig } from '@uniweb/build'
+export default defineFoundationConfig()
+```
+
+The site entry point is equally minimal:
+
+```javascript
+// site/src/main.jsx
+import 'virtual:uniweb-site-entry'
+```
 
 ## The Bigger Picture
 
@@ -122,6 +145,12 @@ npx uniweb@latest <command>
 npm install -g uniweb
 ```
 
+**Requirements:**
+- Node.js 20.19 or later
+- pnpm 9+ (recommended) or npm 10+
+
+Projects use Vite 7 and Tailwind CSS v4 by default.
+
 ## Commands
 
 ### `create`
@@ -214,37 +243,35 @@ A minimal workspace with a site and foundation as sibling packages. This is the
 
 ```
 my-project/
-├── package.json              # Workspace root (includes workspaces field for npm)
+├── package.json              # Workspace root (npm + pnpm compatible)
 ├── pnpm-workspace.yaml       # Pre-configured for evolution (see below)
+├── CLAUDE.md                 # AI assistant instructions
 │
 ├── site/                     # Site package (content + entry)
 │   ├── package.json
-│   ├── vite.config.js
+│   ├── vite.config.js        # 3-line config using defineSiteConfig()
 │   ├── index.html
-│   ├── site.yml
+│   ├── site.yml              # Site configuration (foundation, title, i18n)
 │   ├── src/
-│   │   └── main.jsx          # Thin entry point
-│   ├── pages/                # Content structure
+│   │   └── main.jsx          # 1-line entry: import 'virtual:uniweb-site-entry'
+│   ├── pages/                # Content pages (file-based routing)
 │   │   └── home/
 │   │       ├── page.yml
 │   │       └── 1-hero.md
-│   ├── locales/              # i18n (mirrors pages/)
-│   │   └── es/
-│   │       └── home/
 │   └── public/               # Static assets
 │
 └── foundation/               # Foundation package (components)
     ├── package.json
-    ├── vite.config.js
-    ├── src/
-    │   ├── index.js          # Component registry
-    │   ├── styles.css        # Tailwind
-    │   ├── meta.js           # Foundation metadata
-    │   └── components/
-    │       └── Hero/
-    │           ├── index.jsx
-    │           └── meta.js
-    └── ...
+    ├── vite.config.js        # 3-line config using defineFoundationConfig()
+    └── src/
+        ├── index.js          # Component exports
+        ├── entry-runtime.js  # Runtime entry (imports styles + index)
+        ├── styles.css        # Tailwind CSS v4
+        ├── meta.js           # Foundation metadata
+        └── components/
+            └── Section/
+                ├── index.jsx
+                └── meta.js
 ```
 
 **Key characteristics:**
@@ -260,23 +287,24 @@ A monorepo for multi-site or multi-foundation development.
 
 ```
 my-workspace/
-├── package.json              # Workspace root (includes workspaces field for npm)
+├── package.json              # Workspace root (npm + pnpm compatible)
 ├── pnpm-workspace.yaml       # Same config as single template
+├── CLAUDE.md                 # AI assistant instructions
 │
 ├── sites/
 │   ├── marketing/            # Main marketing site
 │   │   ├── package.json
+│   │   ├── vite.config.js    # 3-line config
 │   │   ├── site.yml
-│   │   ├── src/
-│   │   ├── pages/
-│   │   └── ...
+│   │   ├── src/main.jsx      # 1-line entry
+│   │   └── pages/
 │   └── docs/                 # Documentation site
 │
 └── foundations/
     ├── marketing/            # Marketing foundation
     │   ├── package.json
-    │   ├── src/components/
-    │   └── ...
+    │   ├── vite.config.js    # 3-line config
+    │   └── src/components/
     └── documentation/        # Documentation foundation
 ```
 
@@ -298,15 +326,39 @@ A complete marketing site with landing page components:
 uniweb create my-site --template marketing
 ```
 
-**Includes:**
-- **Hero** — Gradient/light/dark banner with CTAs
-- **Features** — Grid layout with icons
-- **Pricing** — Tiered pricing tables
-- **Testimonials** — Customer quotes
-- **CTA** — Call-to-action sections
+**Includes:** Hero, Features, Pricing, Testimonials, CTA, FAQ, Stats, LogoCloud, Video, Gallery, Team
 
 Perfect for product launches, SaaS websites, and business landing pages.
 
+**Tailwind v3 variant:**
+```bash
+uniweb create my-site --template marketing --variant tailwind3
+```
+
+#### Academic
+
+A professional academic site for researchers, labs, and departments:
+
+```bash
+uniweb create my-site --template academic
+```
+
+**Includes:** ProfileHero, PublicationList, ResearchAreas, TeamGrid, Timeline, ContactCard, Navbar, Footer
+
+Perfect for researcher portfolios, lab websites, and academic department sites.
+
+#### Docs
+
+A documentation site with navigation levels:
+
+```bash
+uniweb create my-site --template docs
+```
+
+**Includes:** Header, LeftPanel, DocSection, CodeBlock, Footer
+
+Perfect for technical documentation, guides, and API references.
+
 ### External Templates
 
 You can use templates from npm or GitHub:
@@ -347,6 +399,52 @@ cd foundation && pnpm add embla-carousel
 # No path gymnastics needed
 ```
 
+## Configuration
+
+### Site Configuration
+
+The `defineSiteConfig()` function handles all Vite configuration for sites:
+
+```javascript
+import { defineSiteConfig } from '@uniweb/build/site'
+
+export default defineSiteConfig({
+  // All options are optional
+  tailwind: true,        // Enable Tailwind CSS v4 (default: true)
+  plugins: [],           // Additional Vite plugins
+  // ...any other Vite config options
+})
+```
+
+### Foundation Configuration
+
+The `defineFoundationConfig()` function handles all Vite configuration for foundations:
+
+```javascript
+import { defineFoundationConfig } from '@uniweb/build'
+
+export default defineFoundationConfig({
+  // All options are optional
+  entry: 'src/entry-runtime.js',     // Entry point path
+  fileName: 'foundation',             // Output file name
+  externals: [],                      // Additional packages to externalize
+  includeDefaultExternals: true,      // Include react, @uniweb/core, etc.
+  tailwind: true,                     // Enable Tailwind CSS v4 Vite plugin
+  sourcemap: true,                    // Generate sourcemaps
+  plugins: [],                        // Additional Vite plugins
+  build: {},                          // Additional Vite build options
+  // ...any other Vite config options
+})
+```
+
+For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
+
+```javascript
+export default defineFoundationConfig({
+  tailwind: false  // Uses PostCSS instead of Vite plugin
+})
+```
+
 ## Foundation Build Process
 
 When you run `uniweb build` on a foundation:

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "uniweb",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
     "uniweb": "src/index.js"
   },
   "files": [
-    "src"
+    "src",
+    "templates"
   ],
   "keywords": [
     "uniweb",
@@ -35,6 +36,6 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.1.8"
+    "@uniweb/build": "0.1.9"
   }
 }

package/templates/_shared/CLAUDE.md.hbs

@@ -0,0 +1,146 @@
+# CLAUDE.md - AI Assistant Instructions
+
+This file provides guidance for AI assistants working with this Uniweb project.
+
+## Project Overview
+
+This is a **Uniweb** project - a component web platform that separates content from code.
+
+```
+{{projectName}}/
+├── foundation/     # React component library (code)
+├── site/           # Content and pages (markdown)
+├── package.json    # Root workspace config
+└── pnpm-workspace.yaml
+```
+
+## Quick Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server (site with foundation)
+pnpm dev
+
+# Build foundation (generates dist/foundation.js and schema.json)
+cd foundation && pnpm build
+
+# Build site for production (outputs to site/dist/)
+cd site && pnpm build
+```
+
+## Key Files
+
+**Site:**
+- `site/vite.config.js` - 3-line config using `defineSiteConfig()` from `@uniweb/build/site`
+- `site/src/main.jsx` - 1-line entry: `import 'virtual:uniweb-site-entry'`
+- `site/site.yml` - Site configuration (foundation path, title, i18n)
+- `site/pages/` - Content pages (file-based routing)
+
+**Foundation:**
+- `foundation/vite.config.js` - 3-line config using `defineFoundationConfig()` from `@uniweb/build`
+- `foundation/src/entry-runtime.js` - Runtime entry point (imports styles + components)
+- `foundation/src/index.js` - Component exports
+- `foundation/src/styles.css` - Tailwind CSS v4 theme
+- `foundation/src/components/*/meta.js` - Component metadata and schema
+
+## Architecture
+
+### Foundation Package (`/foundation`)
+
+The **foundation** is a React component library. Each component:
+
+1. Receives structured content parsed from markdown
+2. Has configurable parameters (theme, layout, etc.)
+3. Renders the content according to its design
+
+**Key directories:**
+- `src/components/*/` - Component implementations
+- `src/components/*/meta.js` - Component metadata and schema
+- `src/styles.css` - Global Tailwind styles
+
+### Site Package (`/site`)
+
+The **site** contains content written in markdown. The runtime loads the foundation and renders content based on component selections.
+
+**Key directories:**
+- `pages/` - Content pages organized in folders
+- `pages/[page-name]/page.yml` - Page metadata
+- `pages/[page-name]/*.md` - Content sections
+
+## Content Authoring
+
+### Section File Format
+
+```markdown
+---
+type: ComponentName
+theme: dark
+layout: center
+---
+
+# Main Headline
+
+Description paragraph.
+
+[Call to Action](#link)
+```
+
+### Content Structure
+
+The semantic parser extracts content into:
+
+- **`content.main.header`**: title, pretitle, subtitle
+- **`content.main.body`**: paragraphs, links, imgs, lists
+- **`content.items`**: Content groups from H3 headings
+
+## Component Development
+
+### Component Interface
+
+```jsx
+function MyComponent({ content, params, block, website }) {
+  const { title } = content.main?.header || {}
+  const { paragraphs = [] } = content.main?.body || {}
+  // ...
+}
+```
+
+### Using @uniweb/kit
+
+```jsx
+import { H1, P, Link, cn } from '@uniweb/kit'
+```
+
+### Component Metadata (`meta.js`)
+
+```javascript
+export default {
+  title: 'Component Name',
+  description: 'What the component does',
+  category: 'Content',
+  elements: { /* content elements */ },
+  properties: { /* configurable params */ },
+}
+```
+
+## Tailwind CSS v4
+
+This project uses Tailwind CSS v4 with the Vite plugin.
+
+**Theme customization** (`foundation/src/styles.css`):
+
+```css
+@import "tailwindcss";
+@source "./components/**/*.{js,jsx}";
+@theme {
+  --color-primary: #3b82f6;
+}
+```
+
+## Resources
+
+- [Uniweb Documentation](https://github.com/uniweb/uniweb)
+- [@uniweb/kit Documentation](https://www.npmjs.com/package/@uniweb/kit)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)

package/templates/_shared/package.json.hbs

@@ -0,0 +1,23 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm --filter site dev",
+    "build": "pnpm --filter foundation build && pnpm --filter site build",
+    "preview": "pnpm --filter site preview"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "workspaces": [
+    "site",
+    "foundation",
+    "sites/*",
+    "foundations/*"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "sharp"]
+  }
+}

package/templates/_shared/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - foundation
+  - site
+  - foundations/*
+  - sites/*

package/templates/multi/CLAUDE.md.hbs

@@ -0,0 +1,100 @@
+# CLAUDE.md - AI Assistant Instructions
+
+This file provides guidance for AI assistants working with this Uniweb multi-site workspace.
+
+## Project Overview
+
+This is a **Uniweb multi-site workspace** - supporting multiple sites and foundations.
+
+```
+{{projectName}}/
+├── foundations/        # Shared component libraries
+│   └── default/        # Default foundation
+├── sites/              # Content sites
+│   └── main/           # Main site
+├── package.json        # Root workspace config
+└── pnpm-workspace.yaml
+```
+
+## Quick Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start main site development
+pnpm dev
+
+# Start all sites in parallel
+pnpm dev:all
+
+# Build main site
+pnpm build
+
+# Build all sites
+pnpm build:all
+```
+
+## Adding New Sites
+
+1. Copy an existing site directory:
+   ```bash
+   cp -r sites/main sites/newsite
+   ```
+
+2. Update `sites/newsite/package.json` with a unique name
+
+3. Update `sites/newsite/site.yml` with site configuration
+
+4. Run `pnpm install` to link the new site
+
+## Adding New Foundations
+
+1. Copy an existing foundation:
+   ```bash
+   cp -r foundations/default foundations/newfoundation
+   ```
+
+2. Update `foundations/newfoundation/package.json` with a unique name
+
+3. In your site's `site.yml`, reference the foundation:
+   ```yaml
+   foundation: newfoundation
+   ```
+
+4. In your site's `package.json`, add the dependency:
+   ```json
+   "dependencies": {
+     "newfoundation": "file:../../foundations/newfoundation"
+   }
+   ```
+
+## Key Files
+
+**Sites:**
+- `sites/*/vite.config.js` - 3-line config using `defineSiteConfig()` from `@uniweb/build/site`
+- `sites/*/src/main.jsx` - 1-line entry: `import 'virtual:uniweb-site-entry'`
+- `sites/*/site.yml` - Site configuration (foundation reference, title, i18n)
+- `sites/*/pages/` - Content pages (file-based routing)
+
+**Foundations:**
+- `foundations/*/vite.config.js` - 3-line config using `defineFoundationConfig()` from `@uniweb/build`
+- `foundations/*/src/entry-runtime.js` - Runtime entry point
+- `foundations/*/src/styles.css` - Tailwind CSS v4 theme
+- `foundations/*/src/components/*/meta.js` - Component metadata
+
+## Architecture
+
+### Foundations (`/foundations/*`)
+
+Each foundation is a React component library. Sites can share foundations or have their own.
+
+### Sites (`/sites/*`)
+
+Each site contains content in markdown. A site references one foundation for its components.
+
+## Resources
+
+- [Uniweb Documentation](https://github.com/uniweb/uniweb)
+- [@uniweb/kit Documentation](https://www.npmjs.com/package/@uniweb/kit)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)

package/templates/multi/README.md.hbs

@@ -0,0 +1,96 @@
+# {{projectName}}
+
+A multi-site workspace built with [Uniweb](https://github.com/uniweb/uniweb) — a component web platform that separates content from code.
+
+## Quick Start
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start main site development
+```
+
+Visit `http://localhost:5173` to see your site.
+
+## Project Structure
+
+```
+{{projectName}}/
+├── foundations/         # Shared component libraries
+│   └── default/         # Default foundation
+│       ├── src/
+│       │   ├── components/
+│       │   └── styles.css
+│       └── vite.config.js
+│
+├── sites/               # Content sites
+│   └── main/            # Main site
+│       ├── pages/
+│       ├── site.yml
+│       ├── src/main.jsx
+│       └── vite.config.js
+│
+├── CLAUDE.md            # AI assistant instructions
+└── README.md            # This file
+```
+
+## Commands
+
+```bash
+pnpm dev           # Start main site
+pnpm dev:all       # Start all sites in parallel
+pnpm build         # Build main site
+pnpm build:all     # Build all sites
+```
+
+## Adding a New Site
+
+1. Copy an existing site:
+   ```bash
+   cp -r sites/main sites/newsite
+   ```
+
+2. Update `sites/newsite/package.json` with a unique name
+
+3. Update `sites/newsite/site.yml` with site configuration
+
+4. Run `pnpm install` to link the new site
+
+## Adding a New Foundation
+
+1. Copy an existing foundation:
+   ```bash
+   cp -r foundations/default foundations/newfoundation
+   ```
+
+2. Update the package.json with a unique name
+
+3. In your site's `site.yml`, reference the foundation:
+   ```yaml
+   foundation: newfoundation
+   ```
+
+4. In your site's `package.json`, add the dependency:
+   ```json
+   "dependencies": {
+     "newfoundation": "file:../../foundations/newfoundation"
+   }
+   ```
+
+## Sharing Foundations
+
+Multiple sites can use the same foundation. Each site references the foundation in its `site.yml` and `package.json`.
+
+This allows:
+- Consistent components across sites
+- Single source of truth for design
+- Foundation updates propagate to all sites
+
+## AI Assistance
+
+See [CLAUDE.md](./CLAUDE.md) for detailed instructions that AI assistants can use.
+
+## Learn More
+
+- [Uniweb Documentation](https://github.com/uniweb/uniweb)
+- [@uniweb/kit Components](https://www.npmjs.com/package/@uniweb/kit)
+- [Tailwind CSS v4](https://tailwindcss.com)

package/templates/multi/foundations/default/package.json.hbs

@@ -0,0 +1,37 @@
+{
+  "name": "default",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles": "./src/styles.css",
+    "./dist": "./dist/foundation.js",
+    "./dist/styles": "./dist/assets/style.css"
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "dev": "vite",
+    "build": "uniweb build",
+    "build:vite": "vite build",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@uniweb/core": "{{version "@uniweb/core"}}",
+    "@uniweb/kit": "{{version "@uniweb/kit"}}"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tailwindcss": "^4.0.0",
+    "uniweb": "{{version "uniweb"}}",
+    "vite": "^7.0.0",
+    "vite-plugin-svgr": "^4.2.0"
+  }
+}