stera-ui 0.3.2 → 0.4.0

package/dist/{chunk-26HP67ZM.js → chunk-67ILD3JO.js}

@@ -1,3 +1,7 @@
+import {
+  fetchRegistryItem
+} from "./chunk-T3QWOVJR.js";
+
 // src/utils/transform.ts
 function applyTransforms(content, ctx, transforms) {
   return transforms.reduce((acc, fn) => fn(acc, ctx), content);
@@ -66,14 +70,22 @@ var TYPE_TO_ALIAS = {
 };
 function resolveAlias(alias, projectRoot) {
   const tsConfig = loadConfig(projectRoot);
-  if (tsConfig.resultType === "success") {
-    const match = createMatchPath(tsConfig.absoluteBaseUrl, tsConfig.paths);
-    const resolved = match(alias, void 0, () => true, [".ts", ".tsx"]);
-    if (resolved) {
-      return path.relative(projectRoot, resolved);
+  if (tsConfig.resultType === "success" && Object.keys(tsConfig.paths).length > 0) {
+    const hasMatchingPrefix = Object.keys(tsConfig.paths).some((key) => {
+      const prefix = key.replace(/\/\*$/, "");
+      return alias === prefix || alias.startsWith(`${prefix}/`);
+    });
+    if (hasMatchingPrefix) {
+      const match = createMatchPath(tsConfig.absoluteBaseUrl, tsConfig.paths);
+      const resolved = match(alias, void 0, () => true, [".ts", ".tsx"]);
+      if (resolved) {
+        return path.relative(projectRoot, resolved);
+      }
     }
   }
-  return alias.replace(/^@\//, "");
+  throw new Error(
+    `Could not resolve alias "${alias}" from tsconfig.json. Ensure compilerOptions.paths defines a mapping for it (e.g. "${alias}/*"), then re-run. See https://ui.stera.sh/docs/installation.`
+  );
 }
 function resolveOutputPath(config, projectRoot, file) {
   const alias = TYPE_TO_ALIAS[file.type];
@@ -129,6 +141,7 @@ function loadConfig2(cwd) {
 // src/utils/detect-project.ts
 import fs2 from "fs";
 import path3 from "path";
+import { loadConfig as loadConfig3 } from "tsconfig-paths";
 function hasFile(cwd, filenames) {
   return filenames.some((f) => fs2.existsSync(path3.join(cwd, f)));
 }
@@ -182,21 +195,84 @@ function detectProject(cwd) {
   }
   return { hasSrc, framework, rsc, existingCssFile, layoutFile };
 }
+function detectAliasPrefix(cwd) {
+  let tsConfig;
+  try {
+    tsConfig = loadConfig3(cwd);
+  } catch {
+    return null;
+  }
+  if (tsConfig.resultType !== "success" || Object.keys(tsConfig.paths).length === 0) {
+    return null;
+  }
+  for (const [alias, targets] of Object.entries(tsConfig.paths)) {
+    if (targets.includes("./*") || targets.includes("./src/*") || targets.includes("./app/*")) {
+      return alias.replace(/\/\*$/, "");
+    }
+  }
+  const first = Object.keys(tsConfig.paths)[0];
+  return first ? first.replace(/\/\*$/, "") : null;
+}
 
-// src/utils/detect-globals.ts
-import fs3 from "fs";
+// src/utils/write-stera-css.ts
+import fs3 from "fs/promises";
 import path4 from "path";
-function hasGlobalsCss(config, projectRoot) {
-  const cssPath = path4.resolve(projectRoot, config.css);
-  if (!fs3.existsSync(cssPath)) {
-    return false;
+function stripImportLines(content) {
+  const lines = content.split("\n");
+  const imports = [];
+  const kept = [];
+  for (const line of lines) {
+    if (line.trim().match(/^@import\s+["'].+["']/)) {
+      if (!line.trim().match(/^@import\s+["']tailwindcss["']/)) {
+        imports.push(line.trim());
+      }
+    } else {
+      kept.push(line);
+    }
   }
-  const steraPath = path4.join(path4.dirname(cssPath), "stera-ui.css");
-  return fs3.existsSync(steraPath);
+  return { content: kept.join("\n"), imports };
+}
+async function writeSteraUiCss(config, cwd) {
+  const item = await fetchRegistryItem("globals");
+  const rawContent = item.files?.[0]?.content ?? "";
+  const { content, imports } = stripImportLines(rawContent);
+  const cssDir = path4.dirname(path4.resolve(cwd, config.css));
+  const steraUiPath = path4.join(cssDir, "stera-ui.css");
+  await fs3.mkdir(cssDir, { recursive: true });
+  await fs3.writeFile(steraUiPath, content, "utf-8");
+  return {
+    steraUiPath,
+    extraImports: imports,
+    dependencies: item.dependencies ?? []
+  };
+}
+
+// src/utils/css-imports.ts
+import fs4 from "fs/promises";
+async function insertImportLine(filePath, importStatement) {
+  const content = await fs4.readFile(filePath, "utf-8");
+  const importPath = importStatement.match(/["']([^"']+)["']/)?.[1];
+  if (importPath) {
+    const escaped = importPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`@import\\s+["']${escaped}["']`).test(content)) return;
+  }
+  const lines = content.split("\n");
+  let lastImportIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("@import")) {
+      lastImportIndex = i;
+    }
+  }
+  if (lastImportIndex >= 0) {
+    lines.splice(lastImportIndex + 1, 0, importStatement);
+  } else {
+    lines.unshift(importStatement);
+  }
+  await fs4.writeFile(filePath, lines.join("\n"), "utf-8");
 }
 
 // src/utils/install-deps.ts
-import fs4 from "fs";
+import fs5 from "fs";
 import path5 from "path";
 import { detect } from "@antfu/ni";
 import { execa } from "execa";
@@ -285,9 +361,9 @@ async function installDependencies(deps, cwd) {
   if (deps.length === 0) return;
   const pkgPath = path5.join(cwd, "package.json");
   let existing = /* @__PURE__ */ new Set();
-  if (fs4.existsSync(pkgPath)) {
+  if (fs5.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+      const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
       existing = new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }));
     } catch {
     }
@@ -314,7 +390,7 @@ or use "pnpm add -w <package>" manually to install at the root.`
 }
 
 // src/utils/write-files.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import path6 from "path";
 import readline from "readline/promises";
 async function confirmOverwrite(relativePath) {
@@ -337,8 +413,8 @@ async function writeComponentFiles(items, config, projectRoot, options = {}) {
     for (const file of item.files ?? []) {
       const outputPath = resolveOutputPath(config, projectRoot, file);
       const relativePath = path6.relative(projectRoot, outputPath);
-      if (fs5.existsSync(outputPath)) {
-        const existing = fs5.readFileSync(outputPath, "utf-8");
+      if (fs6.existsSync(outputPath)) {
+        const existing = fs6.readFileSync(outputPath, "utf-8");
         if (existing === file.content) {
           skipped.push(relativePath);
           continue;
@@ -352,8 +428,8 @@ async function writeComponentFiles(items, config, projectRoot, options = {}) {
         }
       }
       const dir = path6.dirname(outputPath);
-      fs5.mkdirSync(dir, { recursive: true });
-      fs5.writeFileSync(outputPath, file.content ?? "", "utf-8");
+      fs6.mkdirSync(dir, { recursive: true });
+      fs6.writeFileSync(outputPath, file.content ?? "", "utf-8");
       written.push(relativePath);
     }
   }
@@ -361,7 +437,7 @@ async function writeComponentFiles(items, config, projectRoot, options = {}) {
 }
 
 // src/utils/update-fonts.ts
-import { existsSync, promises as fs6 } from "fs";
+import { existsSync, promises as fs7 } from "fs";
 import path7 from "path";
 import {
   Project,
@@ -402,10 +478,10 @@ async function updateFonts(fonts, project, cwd, options = {}) {
   if (!layoutPath) return;
   if (options.silent) {
     try {
-      const layoutContent = await fs6.readFile(layoutPath, "utf-8");
+      const layoutContent = await fs7.readFile(layoutPath, "utf-8");
       const updatedContent = transformLayoutFonts(layoutContent, fonts);
       if (updatedContent !== layoutContent) {
-        await fs6.writeFile(layoutPath, updatedContent, "utf-8");
+        await fs7.writeFile(layoutPath, updatedContent, "utf-8");
       }
     } catch {
     }
@@ -413,10 +489,10 @@ async function updateFonts(fonts, project, cwd, options = {}) {
   }
   const spinner = createSpinner("Updating fonts");
   try {
-    const layoutContent = await fs6.readFile(layoutPath, "utf-8");
+    const layoutContent = await fs7.readFile(layoutPath, "utf-8");
     const updatedContent = transformLayoutFonts(layoutContent, fonts);
     if (updatedContent !== layoutContent) {
-      await fs6.writeFile(layoutPath, updatedContent, "utf-8");
+      await fs7.writeFile(layoutPath, updatedContent, "utf-8");
     }
     spinner.succeed("Updated layout with font imports");
   } catch {
@@ -679,7 +755,9 @@ export {
   findConfigPath,
   loadConfig2 as loadConfig,
   detectProject,
-  hasGlobalsCss,
+  detectAliasPrefix,
+  writeSteraUiCss,
+  insertImportLine,
   brand,
   dim,
   LOGO,

package/dist/cli.js

@@ -111,14 +111,22 @@ var TYPE_TO_ALIAS = {
 };
 function resolveAlias(alias, projectRoot) {
   const tsConfig = loadConfig2(projectRoot);
-  if (tsConfig.resultType === "success") {
-    const match = createMatchPath(tsConfig.absoluteBaseUrl, tsConfig.paths);
-    const resolved = match(alias, void 0, () => true, [".ts", ".tsx"]);
-    if (resolved) {
-      return path2.relative(projectRoot, resolved);
+  if (tsConfig.resultType === "success" && Object.keys(tsConfig.paths).length > 0) {
+    const hasMatchingPrefix = Object.keys(tsConfig.paths).some((key) => {
+      const prefix = key.replace(/\/\*$/, "");
+      return alias === prefix || alias.startsWith(`${prefix}/`);
+    });
+    if (hasMatchingPrefix) {
+      const match = createMatchPath(tsConfig.absoluteBaseUrl, tsConfig.paths);
+      const resolved = match(alias, void 0, () => true, [".ts", ".tsx"]);
+      if (resolved) {
+        return path2.relative(projectRoot, resolved);
+      }
     }
   }
-  return alias.replace(/^@\//, "");
+  throw new Error(
+    `Could not resolve alias "${alias}" from tsconfig.json. Ensure compilerOptions.paths defines a mapping for it (e.g. "${alias}/*"), then re-run. See https://ui.stera.sh/docs/installation.`
+  );
 }
 function resolveOutputPath(config, projectRoot, file) {
   const alias = TYPE_TO_ALIAS[file.type];
@@ -196,7 +204,6 @@ var dim = (text) => wrap(DIM, text);
 var LOGO = brand("\u273B");
 var CHECK = brand("\u2713");
 var CROSS = "\u2717";
-var WARN = "!";
 
 // src/utils/spinner.ts
 var FRAMES = ["\u2022", "\u2726", "\u2736", "\u273B"].map(brand);
@@ -354,22 +361,78 @@ var transformImports = (content, ctx) => {
   );
 };
 
-// src/utils/detect-globals.ts
-import fs4 from "fs";
+// src/utils/write-stera-css.ts
+import fs4 from "fs/promises";
 import path5 from "path";
-function hasGlobalsCss(config, projectRoot) {
-  const cssPath = path5.resolve(projectRoot, config.css);
-  if (!fs4.existsSync(cssPath)) {
-    return false;
+function stripImportLines(content) {
+  const lines = content.split("\n");
+  const imports = [];
+  const kept = [];
+  for (const line of lines) {
+    if (line.trim().match(/^@import\s+["'].+["']/)) {
+      if (!line.trim().match(/^@import\s+["']tailwindcss["']/)) {
+        imports.push(line.trim());
+      }
+    } else {
+      kept.push(line);
+    }
   }
-  const steraPath = path5.join(path5.dirname(cssPath), "stera-ui.css");
-  return fs4.existsSync(steraPath);
+  return { content: kept.join("\n"), imports };
+}
+async function writeSteraUiCss(config, cwd) {
+  const item = await fetchRegistryItem("globals");
+  const rawContent = item.files?.[0]?.content ?? "";
+  const { content, imports } = stripImportLines(rawContent);
+  const cssDir = path5.dirname(path5.resolve(cwd, config.css));
+  const steraUiPath = path5.join(cssDir, "stera-ui.css");
+  await fs4.mkdir(cssDir, { recursive: true });
+  await fs4.writeFile(steraUiPath, content, "utf-8");
+  return {
+    steraUiPath,
+    extraImports: imports,
+    dependencies: item.dependencies ?? []
+  };
 }
 
 // src/commands/add.ts
 var transforms = [transformImports];
 async function add(components, options) {
   const cwd = options.cwd ? path6.resolve(options.cwd) : process.cwd();
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    console.error(`  ${CROSS}  ${CONFIG_FILE} not found. Run "stera-ui init" first.`);
+    process.exit(1);
+  }
+  const config = loadConfig(cwd);
+  if (!config) {
+    console.error(`  ${CROSS}  Failed to parse ${CONFIG_FILE}.`);
+    process.exit(1);
+  }
+  const projectRoot = path6.dirname(configPath);
+  if (components.includes("globals")) {
+    if (components.length > 1) {
+      console.error(
+        `  ${CROSS}  "stera-ui add globals" refreshes design tokens and cannot be combined with other components.`
+      );
+      console.error(
+        `     Run "stera-ui add globals" and "stera-ui add ${components.filter((c) => c !== "globals").join(" ")}" separately.`
+      );
+      process.exit(1);
+    }
+    const spinner2 = createSpinner("Refreshing base styles");
+    let result;
+    try {
+      result = await writeSteraUiCss(config, projectRoot);
+    } catch (err) {
+      spinner2.fail("Failed to refresh base styles");
+      throw err;
+    }
+    spinner2.succeed(
+      `Refreshed ${path6.relative(projectRoot, result.steraUiPath)}`
+    );
+    console.log("");
+    return;
+  }
   const spinner = createSpinner("Fetching registry");
   try {
     for (const name of components) {
@@ -384,17 +447,6 @@ async function add(components, options) {
     spinner.fail("Failed to fetch registry");
     throw err;
   }
-  const configPath = findConfigPath(cwd);
-  if (!configPath) {
-    spinner.fail(`${CONFIG_FILE} not found. Run "stera-ui init" first.`);
-    process.exit(1);
-  }
-  const config = loadConfig(cwd);
-  if (!config) {
-    spinner.fail(`Failed to parse ${CONFIG_FILE}.`);
-    process.exit(1);
-  }
-  const projectRoot = path6.dirname(configPath);
   let resolved;
   try {
     resolved = await resolveDependencies(components);
@@ -403,14 +455,6 @@ async function add(components, options) {
     throw err;
   }
   spinner.succeed("Registry resolved");
-  const isAddingGlobals = components.includes("globals");
-  if (!isAddingGlobals && !hasGlobalsCss(config, projectRoot)) {
-    console.warn(`
-  ${WARN}  Stera design tokens not found in ${config.css}`);
-    console.warn(`     Components may not render correctly.`);
-    console.warn(`     Run "stera-ui add globals" to install base styles.
-`);
-  }
   for (const item of resolved) {
     for (const file of item.files ?? []) {
       if (file.content) {
@@ -462,13 +506,15 @@ async function add(components, options) {
 }
 
 // src/commands/init.ts
-import fs9 from "fs";
+import fs10 from "fs";
+import fsp from "fs/promises";
 import path10 from "path";
 import { select } from "@inquirer/prompts";
 
 // src/utils/detect-project.ts
 import fs5 from "fs";
 import path7 from "path";
+import { loadConfig as loadConfig3 } from "tsconfig-paths";
 function hasFile(cwd, filenames) {
   return filenames.some((f) => fs5.existsSync(path7.join(cwd, f)));
 }
@@ -522,6 +568,24 @@ function detectProject(cwd) {
   }
   return { hasSrc, framework, rsc, existingCssFile, layoutFile };
 }
+function detectAliasPrefix(cwd) {
+  let tsConfig;
+  try {
+    tsConfig = loadConfig3(cwd);
+  } catch {
+    return null;
+  }
+  if (tsConfig.resultType !== "success" || Object.keys(tsConfig.paths).length === 0) {
+    return null;
+  }
+  for (const [alias, targets] of Object.entries(tsConfig.paths)) {
+    if (targets.includes("./*") || targets.includes("./src/*") || targets.includes("./app/*")) {
+      return alias.replace(/\/\*$/, "");
+    }
+  }
+  const first = Object.keys(tsConfig.paths)[0];
+  return first ? first.replace(/\/\*$/, "") : null;
+}
 
 // src/utils/detect-fonts.ts
 import fs6 from "fs";
@@ -952,9 +1016,33 @@ function parseTemplateLiteralToCnArgs(templateLiteral) {
   return [...staticArgs, ...variableArgs];
 }
 
+// src/utils/css-imports.ts
+import fs9 from "fs/promises";
+async function insertImportLine(filePath, importStatement) {
+  const content = await fs9.readFile(filePath, "utf-8");
+  const importPath = importStatement.match(/["']([^"']+)["']/)?.[1];
+  if (importPath) {
+    const escaped = importPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`@import\\s+["']${escaped}["']`).test(content)) return;
+  }
+  const lines = content.split("\n");
+  let lastImportIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("@import")) {
+      lastImportIndex = i;
+    }
+  }
+  if (lastImportIndex >= 0) {
+    lines.splice(lastImportIndex + 1, 0, importStatement);
+  } else {
+    lines.unshift(importStatement);
+  }
+  await fs9.writeFile(filePath, lines.join("\n"), "utf-8");
+}
+
 // src/commands/init.ts
 var DEFAULT_FONT_NAMES = ["font-geist", "font-geist-mono"];
-function buildConfig(project, strategy) {
+function buildConfig(project, strategy, aliasPrefix) {
   let cssPath;
   if (project.existingCssFile) {
     cssPath = project.existingCssFile;
@@ -968,53 +1056,17 @@ function buildConfig(project, strategy) {
     version: 1,
     css: cssPath,
     aliases: {
-      components: "@/components",
-      utils: "@/lib/utils",
-      ui: "@/components/ui",
-      lib: "@/lib",
-      hooks: "@/hooks"
+      components: `${aliasPrefix}/components`,
+      utils: `${aliasPrefix}/lib/utils`,
+      ui: `${aliasPrefix}/components/ui`,
+      lib: `${aliasPrefix}/lib`,
+      hooks: `${aliasPrefix}/hooks`
     },
     fonts: {
       strategy
     }
   };
 }
-function stripImportLines(content) {
-  const lines = content.split("\n");
-  const imports = [];
-  const kept = [];
-  for (const line of lines) {
-    if (line.trim().match(/^@import\s+["'].+["']/)) {
-      if (!line.trim().match(/^@import\s+["']tailwindcss["']/)) {
-        imports.push(line.trim());
-      }
-    } else {
-      kept.push(line);
-    }
-  }
-  return { content: kept.join("\n"), imports };
-}
-function insertImportLine(filePath, importStatement) {
-  const content = fs9.readFileSync(filePath, "utf-8");
-  const importPath = importStatement.match(/["']([^"']+)["']/)?.[1];
-  if (importPath) {
-    const escaped = importPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (new RegExp(`@import\\s+["']${escaped}["']`).test(content)) return;
-  }
-  const lines = content.split("\n");
-  let lastImportIndex = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trim().startsWith("@import")) {
-      lastImportIndex = i;
-    }
-  }
-  if (lastImportIndex >= 0) {
-    lines.splice(lastImportIndex + 1, 0, importStatement);
-  } else {
-    lines.unshift(importStatement);
-  }
-  fs9.writeFileSync(filePath, lines.join("\n"), "utf-8");
-}
 async function promptFontStrategy(detected, skipPrompts) {
   const hasExistingFonts = detected.hasNextFont || detected.hasFontFace || detected.hasGoogleFontsLink;
   const defaultStrategy = hasExistingFonts ? "keep-existing" : "stera-default";
@@ -1077,26 +1129,17 @@ async function fetchDefaultFonts() {
 }
 async function executeFontStrategy(strategy, project, detected, config, cwd) {
   if (strategy === "skip") return;
+  const cssDir = path10.dirname(path10.resolve(cwd, config.css));
+  const steraUiPath = path10.join(cssDir, "stera-ui.css");
   if (strategy === "keep-existing") {
-    const cssPath = path10.resolve(cwd, config.css);
-    const cssDir = path10.dirname(cssPath);
-    if (fs9.existsSync(cssPath)) {
-      const fontFamily = detected.fontFamilies.length > 0 ? detected.fontFamilies[0] : null;
-      const fontValue = detected.nextFontVariable ? `var(${detected.nextFontVariable})` : fontFamily ?? "Geist";
-      const patched = patchCssVariables(cssPath, {
-        "--font-heading": fontValue,
-        "--font-sans": fontValue
-      });
-      const steraUiPath = path10.join(cssDir, "stera-ui.css");
-      if (fs9.existsSync(steraUiPath)) {
-        patchCssVariables(steraUiPath, {
-          "--font-heading": fontValue,
-          "--font-sans": fontValue
-        });
-      }
-      if (patched.length > 0) {
-        console.log(`  ${CHECK}  Updated font variables to use ${fontValue}`);
-      }
+    const fontFamily = detected.fontFamilies.length > 0 ? detected.fontFamilies[0] : null;
+    const fontValue = detected.nextFontVariable ? `var(${detected.nextFontVariable})` : fontFamily ?? "Geist";
+    const patched = patchCssVariables(steraUiPath, {
+      "--font-heading": fontValue,
+      "--font-sans": fontValue
+    });
+    if (patched.length > 0) {
+      console.log(`  ${CHECK}  Updated font variables to use ${fontValue}`);
     }
     return;
   }
@@ -1107,25 +1150,15 @@ async function executeFontStrategy(strategy, project, detected, config, cwd) {
     await installDependencies(fontTree.dependencies, cwd);
   }
   if (fontTree.cssImports.length > 0) {
-    const cssPath = path10.resolve(cwd, config.css);
-    const cssDir = path10.dirname(cssPath);
-    const targetCss = fs9.existsSync(path10.join(cssDir, "stera-ui.css")) ? path10.join(cssDir, "stera-ui.css") : cssPath;
-    if (fs9.existsSync(targetCss)) {
-      for (const importLine of fontTree.cssImports) {
-        insertImportLine(targetCss, importLine);
-      }
-      console.log(`  ${CHECK}  Added font imports to ${path10.relative(cwd, targetCss)}`);
+    for (const importLine of fontTree.cssImports) {
+      await insertImportLine(steraUiPath, importLine);
     }
+    console.log(`  ${CHECK}  Added font imports to ${path10.relative(cwd, steraUiPath)}`);
   }
   if (Object.keys(fontTree.cssVars).length > 0) {
-    const cssPath = path10.resolve(cwd, config.css);
-    const cssDir = path10.dirname(cssPath);
-    const targetCss = fs9.existsSync(path10.join(cssDir, "stera-ui.css")) ? path10.join(cssDir, "stera-ui.css") : cssPath;
-    if (fs9.existsSync(targetCss)) {
-      const patched = patchCssVariables(targetCss, fontTree.cssVars);
-      if (patched.length > 0) {
-        console.log(`  ${CHECK}  Updated font variables in ${path10.relative(cwd, targetCss)}`);
-      }
+    const patched = patchCssVariables(steraUiPath, fontTree.cssVars);
+    if (patched.length > 0) {
+      console.log(`  ${CHECK}  Updated font variables in ${path10.relative(cwd, steraUiPath)}`);
     }
   }
   await updateFonts(fonts, project, cwd);
@@ -1142,13 +1175,26 @@ async function init(options) {
     return;
   }
   const pkgPath = path10.join(cwd, "package.json");
-  if (!fs9.existsSync(pkgPath)) {
+  if (!fs10.existsSync(pkgPath)) {
     console.error(
       "  Error: No package.json found. Please run this in a project directory."
     );
     process.exit(1);
   }
   const project = detectProject(cwd);
+  const aliasPrefix = detectAliasPrefix(cwd);
+  if (!aliasPrefix) {
+    console.error("");
+    console.error("  Error: No import alias found in your tsconfig.json file.");
+    console.error(
+      '  Stera UI requires a path alias (e.g. "@/*": ["./src/*"]) in compilerOptions.paths.'
+    );
+    console.error(
+      "  See https://ui.stera.sh/docs/installation for setup instructions per framework."
+    );
+    console.error("");
+    process.exit(1);
+  }
   const frameworkName = project.framework === "next" ? "Next.js" : project.framework === "vite" ? "Vite" : null;
   const parts = [];
   if (frameworkName) parts.push(frameworkName);
@@ -1162,60 +1208,44 @@ async function init(options) {
     detectedFonts,
     options.yes ?? false
   );
-  const config = buildConfig(project, strategy);
+  const config = buildConfig(project, strategy, aliasPrefix);
   const configPath = path10.join(cwd, CONFIG_FILE);
-  fs9.writeFileSync(
+  fs10.writeFileSync(
     configPath,
     JSON.stringify(config, null, 2) + "\n",
     "utf-8"
   );
   console.log(`  ${CHECK}  Created components.json`);
-  const cssDir = path10.dirname(path10.resolve(cwd, config.css));
-  if (project.existingCssFile) {
-    if (hasGlobalsCss(config, cwd)) {
-      console.log(
-        `  ${CHECK}  Stera already initialised ${dim(`(${path10.join(path10.dirname(project.existingCssFile), "stera-ui.css")} exists)`)}`
-      );
-    } else {
-      const fetchSpinner = createSpinner("Fetching base styles");
-      let globalsItem;
-      try {
-        globalsItem = await fetchRegistryItem("globals");
-      } catch {
-        fetchSpinner.fail("Base styles not found \u2014 skipping");
-        globalsItem = null;
-      }
-      if (globalsItem) {
-        fetchSpinner.succeed("Base styles resolved");
-        const globalsContent = globalsItem.files?.[0]?.content ?? "";
-        const { content: steraUiContent, imports } = stripImportLines(globalsContent);
-        const steraUiPath = path10.join(cssDir, "stera-ui.css");
-        fs9.mkdirSync(cssDir, { recursive: true });
-        fs9.writeFileSync(steraUiPath, steraUiContent, "utf-8");
-        console.log(`  ${CHECK}  Created ${path10.relative(cwd, steraUiPath)}`);
-        const existingCssPath = path10.resolve(cwd, project.existingCssFile);
-        for (const imp of imports) {
-          insertImportLine(existingCssPath, imp);
-        }
-        insertImportLine(existingCssPath, "@import './stera-ui.css';");
-        console.log(`  ${CHECK}  Added @import to ${project.existingCssFile}`);
-      }
+  const fetchSpinner = createSpinner("Fetching base styles");
+  let steraCssResult;
+  try {
+    steraCssResult = await writeSteraUiCss(config, cwd);
+  } catch (err) {
+    fetchSpinner.fail("Failed to fetch base styles");
+    throw err;
+  }
+  fetchSpinner.succeed("Base styles resolved");
+  console.log(
+    `  ${CHECK}  Created ${path10.relative(cwd, steraCssResult.steraUiPath)}`
+  );
+  const globalsPath = project.existingCssFile ? path10.resolve(cwd, project.existingCssFile) : path10.resolve(cwd, config.css);
+  if (fs10.existsSync(globalsPath)) {
+    for (const imp of steraCssResult.extraImports) {
+      await insertImportLine(globalsPath, imp);
     }
+    await insertImportLine(globalsPath, '@import "./stera-ui.css";');
+    console.log(
+      `  ${CHECK}  Added @import to ${path10.relative(cwd, globalsPath)}`
+    );
   } else {
-    const fetchSpinner = createSpinner("Fetching base styles");
-    let resolved;
-    try {
-      resolved = await resolveDependencies(["globals"]);
-    } catch (err) {
-      fetchSpinner.fail("Failed to fetch base styles");
-      throw err;
-    }
-    fetchSpinner.succeed("Base styles resolved");
-    const filtered = resolved.filter((item) => item.name !== "fonts");
-    const { written } = await writeComponentFiles(filtered, config, cwd);
-    for (const file of written) {
-      console.log(`  ${CHECK}  Created ${file}`);
-    }
+    await fsp.mkdir(path10.dirname(globalsPath), { recursive: true });
+    const scaffold = [
+      '@import "tailwindcss";',
+      ...steraCssResult.extraImports,
+      '@import "./stera-ui.css";'
+    ].join("\n") + "\n";
+    await fsp.writeFile(globalsPath, scaffold, "utf-8");
+    console.log(`  ${CHECK}  Created ${path10.relative(cwd, globalsPath)}`);
   }
   await executeFontStrategy(
     strategy,
@@ -1224,21 +1254,10 @@ async function init(options) {
     config,
     cwd
   );
-  const depsSpinner = createSpinner("Fetching package list");
-  let globalsForDeps;
-  try {
-    globalsForDeps = await fetchRegistryItem("globals");
-  } catch {
-    depsSpinner.fail("Package list unavailable \u2014 skipping");
-    globalsForDeps = null;
-  }
-  if (globalsForDeps) {
-    depsSpinner.succeed("Package list resolved");
-    if (globalsForDeps.dependencies) {
-      const deps = [...new Set(globalsForDeps.dependencies)].sort();
-      console.log("");
-      await installDependencies(deps, cwd);
-    }
+  if (steraCssResult.dependencies.length > 0) {
+    const deps = [...new Set(steraCssResult.dependencies)].sort();
+    console.log("");
+    await installDependencies(deps, cwd);
   }
   console.log("");
   console.log("  Next steps:");

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { fetchRegistryIndex, fetchRegistryItem, getAllComponents, getComponent, resolveDependencies } from './registry/index.js';
 export { RegistryFontItem, RegistryIndex, RegistryItem, RegistryItemFile, RegistryItemFont, RegistryItemType, SteraConfig, configSchema, registryIndexSchema, registryItemFileSchema, registryItemFontSchema, registryItemSchema, registryItemTypeSchema } from './schema/index.js';
-export { CHECK, CONFIG_FILE, CROSS, LOGO, ProjectInfo, TransformContext, TransformFn, WARN, WriteOptions, WriteResult, applyTransforms, brand, createSpinner, detectPackageManager, detectProject, dim, findConfigPath, hasGlobalsCss, installDependencies, loadConfig, massageTreeForFonts, resolveOutputPath, transformImports, updateFonts, writeComponentFiles } from './utils/index.js';
+export { CHECK, CONFIG_FILE, CROSS, LOGO, ProjectInfo, TransformContext, TransformFn, WARN, WriteOptions, WriteResult, WriteSteraCssResult, applyTransforms, brand, createSpinner, detectAliasPrefix, detectPackageManager, detectProject, dim, findConfigPath, insertImportLine, installDependencies, loadConfig, massageTreeForFonts, resolveOutputPath, transformImports, updateFonts, writeComponentFiles, writeSteraUiCss } from './utils/index.js';
 import 'zod';

package/dist/index.js

@@ -1,10 +1,3 @@
-import {
-  fetchRegistryIndex,
-  fetchRegistryItem,
-  getAllComponents,
-  getComponent,
-  resolveDependencies
-} from "./chunk-T3QWOVJR.js";
 import {
   configSchema,
   registryIndexSchema,
@@ -22,19 +15,28 @@ import {
   applyTransforms,
   brand,
   createSpinner,
+  detectAliasPrefix,
   detectPackageManager,
   detectProject,
   dim,
   findConfigPath,
-  hasGlobalsCss,
+  insertImportLine,
   installDependencies,
   loadConfig,
   massageTreeForFonts,
   resolveOutputPath,
   transformImports,
   updateFonts,
-  writeComponentFiles
-} from "./chunk-26HP67ZM.js";
+  writeComponentFiles,
+  writeSteraUiCss
+} from "./chunk-67ILD3JO.js";
+import {
+  fetchRegistryIndex,
+  fetchRegistryItem,
+  getAllComponents,
+  getComponent,
+  resolveDependencies
+} from "./chunk-T3QWOVJR.js";
 export {
   CHECK,
   CONFIG_FILE,
@@ -45,6 +47,7 @@ export {
   brand,
   configSchema,
   createSpinner,
+  detectAliasPrefix,
   detectPackageManager,
   detectProject,
   dim,
@@ -53,7 +56,7 @@ export {
   findConfigPath,
   getAllComponents,
   getComponent,
-  hasGlobalsCss,
+  insertImportLine,
   installDependencies,
   loadConfig,
   massageTreeForFonts,
@@ -66,5 +69,6 @@ export {
   resolveOutputPath,
   transformImports,
   updateFonts,
-  writeComponentFiles
+  writeComponentFiles,
+  writeSteraUiCss
 };

package/dist/utils/index.d.ts

@@ -67,12 +67,46 @@ interface ProjectInfo {
  * - Existing Tailwind CSS entry file
  */
 declare function detectProject(cwd: string): ProjectInfo;
+/**
+ * Detect the alias prefix (e.g. "@" or "~") from the project's tsconfig.json
+ * `compilerOptions.paths`. Mirrors shadcn's approach.
+ *
+ * Returns null when tsconfig can't be loaded or defines no path mappings —
+ * `init` should surface a clear error in that case rather than templating
+ * aliases that won't resolve.
+ */
+declare function detectAliasPrefix(cwd: string): string | null;
+
+interface WriteSteraCssResult {
+    /** Absolute path to the written `stera-ui.css`. */
+    steraUiPath: string;
+    /**
+     * Non-tailwindcss `@import` statements stripped from the registry content
+     * (e.g. `@import "tw-animate-css";`). Callers are expected to ensure these
+     * are present in the user's main globals.css.
+     */
+    extraImports: string[];
+    /** npm packages declared by the globals registry item. */
+    dependencies: string[];
+}
+/**
+ * Fetch the `globals` registry item and write `stera-ui.css` into the
+ * directory that holds the user's configured globals.css. Overwrites
+ * unconditionally — the caller decides when this is appropriate (init or
+ * an explicit `add globals` refresh).
+ *
+ * Does NOT touch the user's globals.css.
+ */
+declare function writeSteraUiCss(config: SteraConfig, cwd: string): Promise<WriteSteraCssResult>;
 
 /**
- * Check if Stera has already been initialised in the user's project.
- * Looks for the presence of `stera-ui.css` alongside the user's CSS file.
+ * Insert an `@import` statement into an existing CSS file, placed after the
+ * last existing `@import` line. Prepends to the file if none exist.
+ *
+ * Idempotent: if an `@import` for the same path already exists, no change
+ * is made.
  */
-declare function hasGlobalsCss(config: SteraConfig, projectRoot: string): boolean;
+declare function insertImportLine(filePath: string, importStatement: string): Promise<void>;
 
 type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
 declare function detectPackageManager(cwd: string): Promise<PackageManager>;
@@ -132,4 +166,4 @@ declare function updateFonts(fonts: RegistryFontItem[], project: ProjectInfo, cw
     silent?: boolean;
 }): Promise<void>;
 
-export { CHECK, CONFIG_FILE, CROSS, LOGO, type ProjectInfo, type TransformContext, type TransformFn, WARN, type WriteOptions, type WriteResult, applyTransforms, brand, createSpinner, detectPackageManager, detectProject, dim, findConfigPath, hasGlobalsCss, installDependencies, loadConfig, massageTreeForFonts, resolveOutputPath, transformImports, updateFonts, writeComponentFiles };
+export { CHECK, CONFIG_FILE, CROSS, LOGO, type ProjectInfo, type TransformContext, type TransformFn, WARN, type WriteOptions, type WriteResult, type WriteSteraCssResult, applyTransforms, brand, createSpinner, detectAliasPrefix, detectPackageManager, detectProject, dim, findConfigPath, insertImportLine, installDependencies, loadConfig, massageTreeForFonts, resolveOutputPath, transformImports, updateFonts, writeComponentFiles, writeSteraUiCss };

package/dist/utils/index.js

@@ -7,19 +7,22 @@ import {
   applyTransforms,
   brand,
   createSpinner,
+  detectAliasPrefix,
   detectPackageManager,
   detectProject,
   dim,
   findConfigPath,
-  hasGlobalsCss,
+  insertImportLine,
   installDependencies,
   loadConfig,
   massageTreeForFonts,
   resolveOutputPath,
   transformImports,
   updateFonts,
-  writeComponentFiles
-} from "../chunk-26HP67ZM.js";
+  writeComponentFiles,
+  writeSteraUiCss
+} from "../chunk-67ILD3JO.js";
+import "../chunk-T3QWOVJR.js";
 export {
   CHECK,
   CONFIG_FILE,
@@ -29,16 +32,18 @@ export {
   applyTransforms,
   brand,
   createSpinner,
+  detectAliasPrefix,
   detectPackageManager,
   detectProject,
   dim,
   findConfigPath,
-  hasGlobalsCss,
+  insertImportLine,
   installDependencies,
   loadConfig,
   massageTreeForFonts,
   resolveOutputPath,
   transformImports,
   updateFonts,
-  writeComponentFiles
+  writeComponentFiles,
+  writeSteraUiCss
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stera-ui",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "Add Stera UI components to your project.",
   "license": "MIT",