uniweb 0.3.2 → 0.3.4

package/README.md

@@ -13,6 +13,20 @@ pnpm install
 pnpm dev
 ```
 
+Open http://localhost:5173 to see your site. Edit files in `site/pages/` and `foundation/src/components/` to see changes instantly.
+
+### Development Commands
+
+Run these from the **project root** (where `pnpm-workspace.yaml` is):
+
+```bash
+pnpm dev        # Start development server
+pnpm build      # Build foundation + site for production
+pnpm preview    # Preview the production build
+```
+
+The `build` command generates static HTML in `site/dist/`. Open those files to verify your output before deploying.
+
 The `marketing` template includes real components (Hero, Features, Pricing, Testimonials, FAQ, and more) with sample content—a working site you can explore and modify.
 
 **Other templates:**
@@ -92,7 +106,16 @@ role: Lead Architect
 ```
 ````
 
-Components receive validated, localized data. Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
+Access the parsed data via `content.data`:
+
+```jsx
+function TeamCard({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} — {member.role}</div>
+}
+```
+
+Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
 
 ### Components as React
 
@@ -634,6 +657,76 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
 
 Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
 
+## Common Gotchas
+
+### Homepage Configuration
+
+Set your homepage with `index:` in `site.yml`:
+
+```yaml
+# site.yml
+index: home  # The page folder that becomes /
+```
+
+The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
+
+Don't confuse this with `pages:` (which explicitly lists pages and hides any not listed).
+
+### Content Shapes
+
+Lists and items in markdown become **objects**, not strings. A bullet list:
+
+```markdown
+- First item
+- Second item
+```
+
+Becomes:
+
+```js
+content.items = [
+  { title: "First item", paragraphs: [], links: [], imgs: [] },
+  { title: "Second item", paragraphs: [], links: [], imgs: [] }
+]
+```
+
+Each item has the same structure as a content block. See [Content Structure](./docs/content-structure.md) for the full shape.
+
+### Tagged Data Blocks
+
+Tagged code blocks like:
+
+````markdown
+```yaml:team-member
+name: Sarah Chen
+role: Lead Architect
+```
+````
+
+Are accessible via `content.data`:
+
+```jsx
+function TeamMember({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} - {member.role}</div>
+}
+```
+
+The tag name (after the colon) becomes the key in `content.data`.
+
+### Root vs Package Commands
+
+In a Uniweb workspace, commands run differently at different levels:
+
+| Location | Command | What it does |
+|----------|---------|--------------|
+| Project root | `pnpm build` | Builds all packages (foundation + site) |
+| Project root | `pnpm dev` | Starts dev server for site |
+| `foundation/` | `uniweb build` | Builds just the foundation |
+| `site/` | `uniweb build` | Builds just the site |
+
+For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
+
 ## Related Packages
 
 - [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.2.1",
-    "@uniweb/core": "0.2.1",
+    "@uniweb/build": "0.2.2",
+    "@uniweb/core": "0.2.2",
     "@uniweb/runtime": "0.3.0",
     "@uniweb/kit": "0.2.1"
   }

package/src/commands/build.js

@@ -10,7 +10,7 @@
  *   uniweb build --prerender         # Build site + pre-render to static HTML (SSG)
  */
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { resolve, join } from 'node:path'
 import { spawn } from 'node:child_process'
 import { writeFile, mkdir } from 'node:fs/promises'
@@ -53,22 +53,51 @@ function info(message) {
 
 /**
  * Detect project type based on directory contents
+ *
+ * Detection priority:
+ * 1. foundation.js → foundation
+ * 2. site.yml → site
+ * 3. src/components/ → foundation (fallback)
+ * 4. pages/ → site (fallback)
+ * 5. pnpm-workspace.yaml or package.json workspaces → workspace
  */
 function detectProjectType(projectDir) {
-  const srcDir = join(projectDir, 'src')
-  const componentsDir = join(srcDir, 'components')
-  const pagesDir = join(projectDir, 'pages')
+  // Primary detection: config files
+  if (existsSync(join(projectDir, 'src', 'foundation.js'))) {
+    return 'foundation'
+  }
 
-  // Foundation: has src/components/ with component folders containing meta.js
-  if (existsSync(componentsDir)) {
+  if (existsSync(join(projectDir, 'site.yml'))) {
+    return 'site'
+  }
+
+  // Fallback detection: directory structure
+  if (existsSync(join(projectDir, 'src', 'components'))) {
     return 'foundation'
   }
 
-  // Site: has pages/ directory
-  if (existsSync(pagesDir)) {
+  if (existsSync(join(projectDir, 'pages'))) {
     return 'site'
   }
 
+  // Workspace: has pnpm-workspace.yaml or package.json with workspaces
+  if (existsSync(join(projectDir, 'pnpm-workspace.yaml'))) {
+    return 'workspace'
+  }
+
+  // Check package.json for workspaces field
+  const packageJsonPath = join(projectDir, 'package.json')
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+      if (packageJson.workspaces) {
+        return 'workspace'
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
   return null
 }
 
@@ -395,6 +424,123 @@ async function buildSite(projectDir, options = {}) {
   }
 }
 
+/**
+ * Check if a directory is a foundation
+ */
+function isFoundation(dir) {
+  // Primary: has foundation.js config
+  if (existsSync(join(dir, 'src', 'foundation.js'))) return true
+  // Fallback: has src/components/
+  if (existsSync(join(dir, 'src', 'components'))) return true
+  return false
+}
+
+/**
+ * Check if a directory is a site
+ */
+function isSite(dir) {
+  // Primary: has site.yml config
+  if (existsSync(join(dir, 'site.yml'))) return true
+  // Fallback: has pages/
+  if (existsSync(join(dir, 'pages'))) return true
+  return false
+}
+
+/**
+ * Discover workspace packages based on workspace config
+ */
+function discoverWorkspacePackages(workspaceDir) {
+  const foundations = []
+  const sites = []
+
+  // Check standard locations
+  const standardFoundation = join(workspaceDir, 'foundation')
+  const standardSite = join(workspaceDir, 'site')
+
+  if (existsSync(standardFoundation) && isFoundation(standardFoundation)) {
+    foundations.push({ name: 'foundation', path: standardFoundation })
+  }
+
+  if (existsSync(standardSite) && isSite(standardSite)) {
+    sites.push({ name: 'site', path: standardSite })
+  }
+
+  // Check multi-site locations (foundations/*, sites/*)
+  const foundationsDir = join(workspaceDir, 'foundations')
+  const sitesDir = join(workspaceDir, 'sites')
+
+  if (existsSync(foundationsDir)) {
+    for (const name of readdirSync(foundationsDir)) {
+      const path = join(foundationsDir, name)
+      if (isFoundation(path)) {
+        foundations.push({ name, path })
+      }
+    }
+  }
+
+  if (existsSync(sitesDir)) {
+    for (const name of readdirSync(sitesDir)) {
+      const path = join(sitesDir, name)
+      if (isSite(path)) {
+        sites.push({ name, path })
+      }
+    }
+  }
+
+  return { foundations, sites }
+}
+
+/**
+ * Build all packages in a workspace
+ */
+async function buildWorkspace(workspaceDir, options = {}) {
+  const { prerenderFlag, noPrerenderFlag } = options
+
+  log(`${colors.cyan}${colors.bright}Building workspace...${colors.reset}`)
+  log('')
+
+  const { foundations, sites } = discoverWorkspacePackages(workspaceDir)
+
+  if (foundations.length === 0 && sites.length === 0) {
+    error('No foundations or sites found in workspace')
+    log('')
+    log('Expected structure:')
+    log('  foundation/     or  foundations/*/')
+    log('  site/           or  sites/*/')
+    process.exit(1)
+  }
+
+  // Build foundations first (sites depend on them)
+  for (const foundation of foundations) {
+    log(`${colors.bright}[${foundation.name}]${colors.reset}`)
+    await buildFoundation(foundation.path)
+    log('')
+  }
+
+  // Build sites
+  for (const site of sites) {
+    log(`${colors.bright}[${site.name}]${colors.reset}`)
+
+    const siteConfig = readSiteConfig(site.path)
+    const configPrerender = siteConfig.build?.prerender === true
+
+    let prerender = configPrerender
+    if (prerenderFlag) prerender = true
+    if (noPrerenderFlag) prerender = false
+
+    // Resolve foundation directory for this site
+    const foundationDir = resolveFoundationDir(site.path, siteConfig)
+
+    await buildSite(site.path, { prerender, foundationDir, siteConfig })
+    log('')
+  }
+
+  // Summary
+  log(`${colors.green}${colors.bright}Workspace build complete!${colors.reset}`)
+  log('')
+  log(`Built ${foundations.length} foundation(s) and ${sites.length} site(s)`)
+}
+
 /**
  * Main build command handler
  */
@@ -430,22 +576,26 @@ export async function build(args = []) {
 
     if (!targetType) {
       error('Could not detect project type')
-      log('Use --target foundation or --target site')
+      log('Use --target foundation or --target site, or run from workspace root')
       process.exit(1)
     }
 
-    info(`Detected project type: ${targetType}`)
+    if (targetType !== 'workspace') {
+      info(`Detected project type: ${targetType}`)
+    }
   }
 
-  // Validate prerender flags are only used with site target
-  if ((prerenderFlag || noPrerenderFlag) && targetType !== 'site') {
-    error('--prerender/--no-prerender can only be used with site builds')
+  // Validate prerender flags are only used with site/workspace target
+  if ((prerenderFlag || noPrerenderFlag) && targetType === 'foundation') {
+    error('--prerender/--no-prerender can only be used with site or workspace builds')
     process.exit(1)
   }
 
   // Run appropriate build
   try {
-    if (targetType === 'foundation') {
+    if (targetType === 'workspace') {
+      await buildWorkspace(projectDir, { prerenderFlag, noPrerenderFlag })
+    } else if (targetType === 'foundation') {
       await buildFoundation(projectDir)
     } else {
       // For sites, read config to determine prerender default

package/src/index.js

@@ -68,10 +68,6 @@ const templates = {
     name: 'Multi-Site Workspace',
     description: 'Multiple sites and foundations in sites/* and foundations/*',
   },
-  template: {
-    name: 'Template Starter',
-    description: 'Create a shareable Uniweb template for npm or GitHub',
-  },
 }
 
 /**
@@ -235,11 +231,6 @@ async function main() {
           description: templates.multi.description,
           value: 'multi',
         },
-        {
-          title: templates.template.name,
-          description: templates.template.description,
-          value: 'template',
-        },
       ],
     },
   ], {
@@ -300,6 +291,11 @@ async function main() {
       })
     } catch (err) {
       error(`Failed to apply template: ${err.message}`)
+      log('')
+      log(`${colors.yellow}Troubleshooting:${colors.reset}`)
+      log(`  • Check your network connection`)
+      log(`  • Official templates require GitHub access (may be blocked by corporate networks)`)
+      log(`  • Try the built-in template instead: ${colors.cyan}uniweb create ${projectName}${colors.reset}`)
       process.exit(1)
     }
   }
@@ -339,6 +335,7 @@ ${colors.bright}Build Options:${colors.reset}
   --foundation-dir   Path to foundation directory (for prerendering)
   --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
 
+  At workspace root, builds all foundations first, then all sites.
   Pre-rendering is enabled by default when build.prerender: true in site.yml
 
 ${colors.bright}Docs Subcommands:${colors.reset}
@@ -359,7 +356,6 @@ ${colors.bright}i18n Commands:${colors.reset}
 ${colors.bright}Template Types:${colors.reset}
   single                        One site + one foundation (default)
   multi                         Multiple sites and foundations
-  template                      Starter for creating shareable templates
   marketing                     Official marketing template
   @scope/template-name          npm package
   github:user/repo              GitHub repository

package/src/templates/resolver.js

@@ -3,7 +3,7 @@
  */
 
 // Built-in templates (file-based in cli/templates/)
-export const BUILTIN_TEMPLATES = ['single', 'multi', 'template']
+export const BUILTIN_TEMPLATES = ['single', 'multi']
 
 // Official templates from @uniweb/templates package (downloaded from GitHub releases)
 export const OFFICIAL_TEMPLATES = ['marketing', 'academic', 'docs', 'international']

package/templates/multi/sites/main/site.yml.hbs

@@ -2,6 +2,9 @@ name: {{projectName}}
 description: Main site for {{projectName}}
 foundation: default
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'
 

package/templates/single/site/site.yml.hbs

@@ -1,5 +1,8 @@
 name: {{projectName}}
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'