tiendu 0.2.3 → 0.3.0

package/README.md

@@ -24,27 +24,33 @@ npm install -g tiendu
 
 ## Quick start
 
+### Buildless theme (simple)
+
 ```bash
-# Create a working directory and enter it
 mkdir my-theme && cd my-theme
-
-# Connect to your store
 tiendu init
-
-# Download the current live theme
 tiendu pull
+tiendu dev
+```
 
-# Start developing with live preview
+### Built theme (TypeScript, npm packages, bundling)
+
+Clone the default theme template, connect to your store, and start developing:
+
+```bash
+git clone <default-theme-repo> my-theme && cd my-theme
+npm install
+tiendu init
 tiendu dev
 ```
 
-`tiendu dev` creates a remote preview of your theme, uploads your local files, watches for changes and syncs them automatically, and prints a shareable URL like:
+`tiendu dev` creates a remote preview, builds your source files, uploads the output, and watches for changes. It prints a shareable URL like:
 
 ```
 http://preview-xxxxxxxxxxxx.tiendu.uy/
 ```
 
-The preview renders with the real Tiendu engine — same output as production. Share the URL with your client or team before publishing.
+The preview renders with the real Tiendu engine — same output as production.
 
 ---
 
@@ -64,7 +70,10 @@ tiendu init
 
 ### `tiendu pull`
 
-Downloads the current live theme from your store as local files. Run this once to get started, or to reset your local files to the published version.
+Downloads the current live theme from your store as local files.
+
+- **Buildless themes:** extracts to the current directory.
+- **Built themes** (with `tiendu.config.json`): extracts to `dist/`.
 
 ```bash
 tiendu pull
@@ -72,9 +81,34 @@ tiendu pull
 
 ---
 
+### `tiendu build`
+
+Builds a theme into its deployable output directory (`dist/`). Only available for built themes (requires `tiendu.config.json`).
+
+```bash
+tiendu build
+```
+
+The build:
+
+1. Copies theme files (`layout/`, `templates/`, `snippets/`, `assets/`) to `dist/`
+2. Discovers entry points in `src/layout/` and `src/templates/`
+3. Bundles JS/TS and CSS via esbuild into `dist/assets/`
+
+Entry naming convention:
+
+- `src/layout/theme.ts` → `dist/assets/layout-theme.bundle.js`
+- `src/templates/product.ts` → `dist/assets/template-product.bundle.js`
+- `src/layout/theme.css` → `dist/assets/layout-theme.bundle.css`
+
+---
+
 ### `tiendu dev`
 
-The main development command. On first run it creates a remote preview, uploads your local files, and starts watching for changes. Every file you save is automatically synced to the preview.
+The main development command.
+
+- **Buildless themes:** watches the current directory and syncs file changes to the preview.
+- **Built themes:** runs `tiendu build` in watch mode first, then watches `dist/` and syncs changes to the preview.
 
 ```bash
 tiendu dev
@@ -89,7 +123,10 @@ tiendu dev
 
 ### `tiendu push`
 
-Zips all local files (excluding dotfiles) and uploads them to the active preview, replacing its content entirely. Use this instead of `tiendu dev` if you prefer manual syncs.
+Zips and uploads files to the active preview, replacing its content entirely.
+
+- **Buildless themes:** uploads from the current directory.
+- **Built themes:** uploads from `dist/`.
 
 ```bash
 tiendu push
@@ -109,7 +146,7 @@ tiendu publish
 
 ### `tiendu preview create [name]`
 
-Creates a new remote preview. Fails with a conflict error if one already exists for your account on this store — delete it first with `tiendu preview delete`.
+Creates a new remote preview.
 
 ```bash
 tiendu preview create
@@ -150,6 +187,8 @@ tiendu preview open
 
 ## Typical workflow
 
+### Buildless
+
 ```
 tiendu init        # one time: connect to your store
 tiendu pull        # one time: download the live theme
@@ -159,6 +198,18 @@ tiendu dev         # develop: edit locally, see changes live at the preview URL
 tiendu publish     # when ready: push to the live storefront
 ```
 
+### Built theme
+
+```
+git clone <template-repo> my-theme
+cd my-theme && npm install
+tiendu init        # one time: connect to your store
+
+tiendu dev         # develop: builds src/, watches dist/, syncs to preview
+
+tiendu publish     # when ready: push to the live storefront
+```
+
 ---
 
 ## How previews work
@@ -173,18 +224,54 @@ A **theme preview** is a remote copy of your theme hosted by Tiendu. It renders
 
 ---
 
-## Local project structure
+## Built themes
+
+A **built theme** is a theme that uses `tiendu.config.json` to enable the build pipeline. It allows:
 
-After `tiendu pull` your directory will look like your store's theme. The `.cli/` folder holds local CLI configuration and is never uploaded to Tiendu.
+- npm packages via a local `package.json`
+- TypeScript (`.ts`) for browser code
+- JS bundling (multiple modules → single versioned bundle)
+- CSS bundling (`@import` support)
+
+### Project structure
 
 ```
 my-theme/
-├── .cli/               # local config (API key, store ID, active preview key)
-├── layout/
-├── templates/
-├── snippets/
-├── assets/
-└── ...
+├── tiendu.config.json    # marks this as a built theme
+├── package.json          # npm dependencies
+├── .gitignore
+├── src/
+│   ├── layout/
+│   │   ├── theme.ts      # layout TS entry → layout-theme.bundle.js
+│   │   └── theme.css     # layout CSS entry → layout-theme.bundle.css
+│   ├── templates/
+│   │   ├── product.ts    # template TS entry → template-product.bundle.js
+│   │   └── product.css   # template CSS entry → template-product.bundle.css
+│   ├── lib/              # shared modules (bundled into entries, not served)
+│   └── css/              # shared CSS (imported by entry CSS)
+├── layout/               # Liquid layouts
+├── templates/            # Liquid templates
+├── snippets/             # Liquid snippets
+├── assets/               # static assets (SVGs, images, fonts)
+└── dist/                 # build output (gitignored, uploaded to Tiendu)
+```
+
+### How it works
+
+1. Source JS/TS/CSS in `src/` is bundled by esbuild into `dist/assets/`
+2. Liquid files and static assets are copied from root to `dist/`
+3. `dist/` is what gets uploaded — it looks like a normal Tiendu theme
+4. Liquid templates reference bundles via `asset_url` (e.g. `{{ 'layout-theme.bundle.js' | asset_url | script_tag }}`)
+
+### tiendu.config.json
+
+Minimal config — the build conventions are hardcoded:
+
+```json
+{
+  "name": "my-theme",
+  "version": "1.0.0"
+}
 ```
 
 ---

package/bin/tiendu.js

@@ -5,6 +5,7 @@ import { pull } from "../lib/pull.mjs";
 import { push } from "../lib/push.mjs";
 import { dev } from "../lib/dev.mjs";
 import { publish } from "../lib/publish.mjs";
+import { build } from "../lib/build.mjs";
 import {
   previewCreate,
   previewShow,
@@ -20,6 +21,7 @@ tiendu — Tiendu theme development CLI
 Usage:
   tiendu init [dir]          Set up a theme project (optionally in a new directory)
   tiendu pull                Download the live theme from your store
+  tiendu build               Build a theme (requires tiendu.config.json)
   tiendu push                Upload local files to the active preview (full replace)
   tiendu dev                 Start dev mode: auto-sync changes to a live preview URL
   tiendu publish             Publish the active preview to the live storefront
@@ -36,6 +38,7 @@ Typical workflow:
   tiendu init my-store       Set up a new project in ./my-store
   cd my-store
   tiendu pull                Download the current live theme
+  tiendu build               Build the theme (for themes with tiendu.config.json)
   tiendu dev                 Edit locally — preview updates in real time
   tiendu publish             Ship to the live storefront when ready
 `;
@@ -68,6 +71,12 @@ const main = async () => {
     return;
   }
 
+  if (command === "build") {
+    const result = await build();
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
   if (command === "push") {
     await push();
     return;

package/lib/build.mjs

@@ -0,0 +1,214 @@
+import { watch } from "node:fs";
+import {
+  cp,
+  mkdir,
+  readdir,
+  rm,
+  stat,
+  copyFile,
+} from "node:fs/promises";
+import path from "node:path";
+import * as esbuild from "esbuild";
+import * as p from "@clack/prompts";
+import { readThemeConfig } from "./config.mjs";
+
+const THEME_DIRS = ["layout", "templates", "snippets", "assets"];
+
+/**
+ * Discover JS/TS and CSS entry points from src/layout and src/templates.
+ * Returns separate maps for JS and CSS to avoid key collisions.
+ */
+const discoverEntryPoints = async (srcDir) => {
+  const jsEntries = {};
+  const cssEntries = {};
+
+  for (const [dir, prefix] of [
+    ["layout", "layout"],
+    ["templates", "template"],
+  ]) {
+    const dirPath = path.join(srcDir, dir);
+    let files;
+    try {
+      files = await readdir(dirPath);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      const ext = path.extname(file);
+      if (![".js", ".ts", ".css"].includes(ext)) continue;
+      const name = path.basename(file, ext);
+      const key = `${prefix}-${name}.bundle`;
+      const fullPath = path.join(dirPath, file);
+      if (ext === ".css") {
+        cssEntries[key] = fullPath;
+      } else {
+        jsEntries[key] = fullPath;
+      }
+    }
+  }
+
+  return { jsEntries, cssEntries };
+};
+
+/**
+ * Copy theme directories (layout/, templates/, snippets/, assets/) to dist/.
+ */
+const copyThemeFiles = async (rootDir, distDir) => {
+  for (const dir of THEME_DIRS) {
+    const src = path.join(rootDir, dir);
+    const dest = path.join(distDir, dir);
+    try {
+      await stat(src);
+    } catch {
+      continue;
+    }
+    await cp(src, dest, { recursive: true });
+  }
+};
+
+/**
+ * Copy a single file from root to dist, preserving relative path.
+ */
+const copySingleFile = async (rootDir, distDir, relativePath) => {
+  const src = path.join(rootDir, relativePath);
+  const dest = path.join(distDir, relativePath);
+  await mkdir(path.dirname(dest), { recursive: true });
+  await copyFile(src, dest);
+};
+
+/**
+ * Run a one-shot build or start watch mode.
+ * @param {{ watch?: boolean }} options
+ * @returns {Promise<{ ok: boolean, cleanup?: () => Promise<void> }>}
+ */
+export const build = async ({ watch: watchMode = false } = {}) => {
+  const rootDir = process.cwd();
+  const srcDir = path.join(rootDir, "src");
+  const distDir = path.join(rootDir, "dist");
+
+  const themeConfig = await readThemeConfig();
+  if (!themeConfig) {
+    p.log.error("No tiendu.config.json found. This is not a built theme.");
+    return { ok: false };
+  }
+
+  // Clean and recreate dist
+  await rm(distDir, { recursive: true, force: true });
+  await mkdir(distDir, { recursive: true });
+
+  // Copy theme files first
+  await copyThemeFiles(rootDir, distDir);
+
+  // Discover entry points (JS and CSS separately to avoid key collisions)
+  const { jsEntries, cssEntries } = await discoverEntryPoints(srcDir);
+  const jsCount = Object.keys(jsEntries).length;
+  const cssCount = Object.keys(cssEntries).length;
+  const entryCount = jsCount + cssCount;
+
+  if (entryCount === 0) {
+    p.log.warn("No entry points found in src/layout or src/templates.");
+    return { ok: true };
+  }
+
+  const outdir = path.join(distDir, "assets");
+  const jsBuildOptions = jsCount > 0
+    ? { entryPoints: jsEntries, bundle: true, format: "esm", target: "es2020", outdir, logLevel: "warning", write: true }
+    : null;
+  const cssBuildOptions = cssCount > 0
+    ? { entryPoints: cssEntries, bundle: true, outdir, logLevel: "warning", write: true }
+    : null;
+
+  if (!watchMode) {
+    // One-shot build
+    try {
+      const builds = [];
+      if (jsBuildOptions) builds.push(esbuild.build(jsBuildOptions));
+      if (cssBuildOptions) builds.push(esbuild.build(cssBuildOptions));
+      await Promise.all(builds);
+      p.log.success(
+        `Built ${entryCount} entry point${entryCount === 1 ? "" : "s"} to dist/`,
+      );
+      return { ok: true };
+    } catch (error) {
+      p.log.error(`Build failed: ${error.message}`);
+      return { ok: false };
+    }
+  }
+
+  // Watch mode — create contexts for both JS and CSS
+  const contexts = [];
+  try {
+    if (jsBuildOptions) {
+      const jsCtx = await esbuild.context(jsBuildOptions);
+      await jsCtx.watch();
+      contexts.push(jsCtx);
+    }
+    if (cssBuildOptions) {
+      const cssCtx = await esbuild.context(cssBuildOptions);
+      await cssCtx.watch();
+      contexts.push(cssCtx);
+    }
+  } catch (error) {
+    p.log.error(`Build failed: ${error.message}`);
+    for (const ctx of contexts) await ctx.dispose();
+    return { ok: false };
+  }
+
+  p.log.success(
+    `Built ${entryCount} entry point${entryCount === 1 ? "" : "s"}. Watching for changes...`,
+  );
+
+  // Watch theme directories for Liquid/static asset changes and copy to dist
+  const themeWatchers = [];
+  const debounceMap = new Map();
+  const DEBOUNCE_MS = 200;
+
+  for (const dir of THEME_DIRS) {
+    const dirPath = path.join(rootDir, dir);
+    try {
+      await stat(dirPath);
+    } catch {
+      continue;
+    }
+
+    const watcher = watch(dirPath, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+      const relativePath = path.join(dir, filename);
+
+      const existing = debounceMap.get(relativePath);
+      if (existing) clearTimeout(existing);
+
+      const timer = setTimeout(async () => {
+        debounceMap.delete(relativePath);
+        try {
+          const fileStat = await stat(path.join(rootDir, relativePath)).catch(
+            () => null,
+          );
+          if (fileStat && fileStat.isFile()) {
+            await copySingleFile(rootDir, distDir, relativePath);
+            console.log(`⟳ ${relativePath}`);
+          } else if (!fileStat) {
+            // File deleted — remove from dist
+            const dest = path.join(distDir, relativePath);
+            await rm(dest, { force: true });
+            console.log(`✕ ${relativePath}`);
+          }
+        } catch (error) {
+          p.log.warn(`Error copying ${relativePath}: ${error.message}`);
+        }
+      }, DEBOUNCE_MS);
+
+      debounceMap.set(relativePath, timer);
+    });
+
+    themeWatchers.push(watcher);
+  }
+
+  const cleanup = async () => {
+    for (const w of themeWatchers) w.close();
+    for (const timer of debounceMap.values()) clearTimeout(timer);
+    for (const ctx of contexts) await ctx.dispose();
+  };
+
+  return { ok: true, cleanup };
+};

package/lib/config.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 const CONFIG_DIR = ".cli";
 const CONFIG_FILE = "config.json";
 const CREDENTIALS_FILE = "credentials.json";
+const THEME_CONFIG_FILE = "tiendu.config.json";
 
 /**
  * @typedef {{ storeId: number, apiBaseUrl: string, previewKey?: string }} TienduConfig
@@ -54,6 +55,25 @@ export const writeCredentials = async (credentials) => {
   );
 };
 
+/** @returns {Promise<object | null>} */
+export const readThemeConfig = async () => {
+  try {
+    const raw = await readFile(
+      path.resolve(process.cwd(), THEME_CONFIG_FILE),
+      "utf-8",
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+/** @returns {Promise<boolean>} */
+export const isBuiltTheme = async () => (await readThemeConfig()) !== null;
+
+/** @returns {string} */
+export const getDistDir = () => path.resolve(process.cwd(), "dist");
+
 /**
  * @returns {Promise<{ config: TienduConfig, credentials: TienduCredentials }>}
  */

package/lib/dev.mjs

@@ -3,7 +3,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { zipSync } from "fflate";
-import { loadConfigOrFail, writeConfig } from "./config.mjs";
+import { loadConfigOrFail, writeConfig, isBuiltTheme, getDistDir } from "./config.mjs";
 import {
   createPreview,
   listPreviews,
@@ -14,6 +14,7 @@ import {
   uploadPreviewFileMultipart,
   uploadPreviewZip,
 } from "./api.mjs";
+import { build } from "./build.mjs";
 
 const isDotfile = (name) => name.startsWith(".");
 
@@ -56,7 +57,19 @@ export const dev = async () => {
   const { config, credentials } = await loadConfigOrFail();
   const { apiBaseUrl, storeId } = config;
   const { apiKey } = credentials;
-  const rootDir = process.cwd();
+  const builtTheme = await isBuiltTheme();
+  const rootDir = builtTheme ? getDistDir() : process.cwd();
+  let buildCleanup = null;
+
+  // For built themes, run the build first (with watch mode)
+  if (builtTheme) {
+    const buildResult = await build({ watch: true });
+    if (!buildResult.ok) {
+      p.log.error("Initial build failed. Fix errors and try again.");
+      process.exit(1);
+    }
+    buildCleanup = buildResult.cleanup;
+  }
 
   const existingPreviewsResult = await listPreviews(
     apiBaseUrl,
@@ -199,9 +212,10 @@ export const dev = async () => {
     debounceMap.set(relativePath, timer);
   });
 
-  const cleanup = () => {
+  const cleanup = async () => {
     watcher.close();
     for (const timer of debounceMap.values()) clearTimeout(timer);
+    if (buildCleanup) await buildCleanup();
     p.outro("Dev mode stopped.");
     process.exit(0);
   };

package/lib/pull.mjs

@@ -1,5 +1,5 @@
 import * as p from "@clack/prompts";
-import { loadConfigOrFail } from "./config.mjs";
+import { loadConfigOrFail, isBuiltTheme, getDistDir } from "./config.mjs";
 import { downloadStorefrontArchive } from "./api.mjs";
 import { extractZip } from "./zip.mjs";
 
@@ -32,7 +32,7 @@ export const pull = async () => {
     `Archive received (${formatBytes(result.data.length)}). Extracting...`,
   );
 
-  const outputDir = process.cwd();
+  const outputDir = (await isBuiltTheme()) ? getDistDir() : process.cwd();
   const extractedFiles = await extractZip(result.data, outputDir);
 
   p.log.success(

package/lib/push.mjs

@@ -2,7 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { zipSync } from "fflate";
-import { loadConfigOrFail } from "./config.mjs";
+import { loadConfigOrFail, isBuiltTheme, getDistDir } from "./config.mjs";
 import { uploadPreviewZip } from "./api.mjs";
 
 /** @param {number} bytes */
@@ -59,7 +59,7 @@ export const push = async () => {
     process.exit(1);
   }
 
-  const rootDir = process.cwd();
+  const rootDir = (await isBuiltTheme()) ? getDistDir() : process.cwd();
   const spinner = p.spinner();
   spinner.start("Packing files...");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiendu",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "CLI para desarrollar y publicar temas en Tiendu",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
+    "esbuild": "^0.24.0",
     "fflate": "^0.8.2"
   }
 }