npm - tkeron - Versions diffs - 4.0.1 → 4.1.0 - Mend

tkeron 4.0.1 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/changelog.md CHANGED Viewed

@@ -1,3 +1,39 @@
+# v4.1.0
+## Documentation & Developer Experience
+### New Features
+- **Added**: `docs/common-issues.md` - Comprehensive troubleshooting guide
+  - Script tag references (most common issue)
+  - Component naming requirements (hyphen mandatory)
+  - File references and relative paths
+  - TypeScript compilation errors
+  - Component resolution rules
+  - Build performance tips
+  - Common AI agent mistakes prevention
+- **Added**: MCP server resource `tkeron://common-issues` for AI agents
+  - Exposes troubleshooting documentation via MCP
+  - Helps AI agents prevent common mistakes
+  - Improves guided project creation
+### Bug Fixes
+- **Improved**: Build error reporting in `buildEntrypoints.ts`
+  - Now shows detailed error messages from Bun.build()
+  - Displays file location and line numbers for errors
+  - Catches and reports exceptions with stack traces
+  - Better diagnosis of bundle failures
+- **Added**: Artifact validation in `buildDir.ts`
+  - Throws clear error if bundle fails
+  - Prevents silent failures
+### Documentation
+- **Updated**: `docs/mcp-server.md` - Documents new common-issues resource
+---
 # v4.0.1
 ## Logger System Migration

package/docs/common-issues.md ADDED Viewed

@@ -0,0 +1,224 @@
+# Common Issues and Solutions
+When building Tkeron projects, AI agents and users may encounter these common issues. This guide helps prevent and resolve them.
+## Script Tag References
+### Issue: "Bundle failed" or Cannot Resolve Module
+**Problem:** HTML references `.js` files but source files are `.ts`
+```html
+<!-- ❌ WRONG -->
+<script src="index.js"></script>
+<!-- ✅ CORRECT -->
+<script type="module" src="index.ts"></script>
+```
+**Why this happens:**
+- Tkeron uses `Bun.build()` to bundle files
+- Bun resolves all file references in HTML (scripts, stylesheets, images)
+- If HTML references `index.js` but only `index.ts` exists, Bun fails with "Could not resolve"
+- The error message may just say "Bundle failed" without details
+**Solution:**
+- Always reference `.ts` files directly in HTML
+- Add `type="module"` attribute to script tags
+- Tkeron will automatically compile `.ts` → `.js` and update the reference
+**Example project structure:**
+```
+websrc/
+├── index.html          <!-- References index.ts -->
+├── index.ts            <!-- Your TypeScript code -->
+└── styles.css
+```
+```html
+<!doctype html>
+<html>
+  <head>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <h1>Hello</h1>
+    <script type="module" src="index.ts"></script>
+  </body>
+</html>
+```
+**After build** (`tk build`):
+```
+web/
+├── index.html          <!-- Now references index.js -->
+├── index.js            <!-- Compiled from index.ts -->
+└── index.css           <!-- Bundled CSS -->
+```
+## Component Naming
+### Issue: Component Name Must Contain Hyphen
+**Problem:** Custom elements without hyphens are invalid
+```html
+<!-- ❌ WRONG -->
+<header></header>
+<!-- Reserved HTML tag -->
+<button></button>
+<!-- Reserved HTML tag -->
+<!-- ✅ CORRECT -->
+<app-header></app-header>
+<my-button></my-button>
+```
+**Why this happens:**
+- HTML custom elements MUST contain at least one hyphen (web standard)
+- This distinguishes them from standard HTML elements
+- Tkeron validates this at build time
+**Solution:**
+- Always use hyphens in component names
+- Match filename to element name (without `.com.html`/`.com.ts`)
+**Examples:**
+```
+user-card.com.html    → <user-card>
+nav-menu.com.html     → <nav-menu>
+blog-post.com.ts      → <blog-post>
+```
+## File References
+### Issue: Assets Not Found After Build
+**Problem:** Relative paths break after build
+```html
+<!-- ❌ WRONG - breaks if HTML moves -->
+<img src="images/logo.png" />
+<!-- ✅ CORRECT - works from any HTML location -->
+<img src="./images/logo.png" />
+```
+**Why this happens:**
+- Tkeron copies your entire source directory structure
+- Relative paths must account for current file location
+- Use `./` for same directory, `../` for parent
+**Solution:**
+- Always use explicit relative paths (`./` or `../`)
+- Keep assets in source directory (`websrc/`)
+- They'll be copied to output (`web/`) in same structure
+## TypeScript Compilation
+### Issue: TypeScript Errors Prevent Build
+**Problem:** Type errors block compilation
+```typescript
+// ❌ WRONG
+const user = { name: "Alice" };
+user.age = 30; // Error: Property 'age' does not exist
+```
+**Why this happens:**
+- Tkeron uses Bun's TypeScript transpiler
+- Type errors can prevent successful builds
+- Missing types for global variables
+**Solution:**
+- Use `tkeron.d.ts` for global type declarations
+- Fix type errors before building
+- Use `any` strategically if types are complex
+```typescript
+// ✅ CORRECT
+const user: { name: string; age?: number } = { name: "Alice" };
+user.age = 30; // OK
+```
+## Component Resolution
+### Issue: Component Not Found
+**Problem:** Tkeron can't find your component file
+```html
+<!-- In blog/post.html -->
+<user-card></user-card>
+```
+**Why this happens:**
+- Tkeron searches in 2 locations only:
+  1. Same directory as HTML file
+  2. Root directory (`websrc/`)
+- Not in subdirectories or parent directories (except root)
+**Solution:**
+Either place component:
+- In `blog/user-card.com.html` (next to `post.html`)
+- Or in `websrc/user-card.com.html` (root, available everywhere)
+## Build Performance
+### Issue: Slow Builds
+**Problem:** Large projects take time to build
+**Why this happens:**
+- Tkeron processes all files on every build
+- Many components create processing overhead
+- Large assets slow down copying
+**Solution:**
+- Use `tk dev` for development (hot reload)
+- Only use `tk build` for production builds
+- Keep assets reasonably sized
+- Avoid excessive component nesting
+## Common AI Agent Mistakes
+When AI agents build Tkeron projects, watch for:
+1. **Script references**: Always `.ts` in HTML, never `.js`
+2. **Component names**: Must contain hyphen
+3. **Type safety**: Don't over-complicate with types
+4. **File paths**: Use explicit relative paths (`./`, `../`)
+## Preventing Issues
+**Before creating a Tkeron project:**
+- ✅ Reference `.ts` files in HTML (Tkeron handles compilation)
+- ✅ Use hyphens in all component names
+- ✅ Use `./` for same-directory asset references
+- ✅ Test with `tk dev` before building
+- ✅ Keep components simple and focused
+**After encountering errors:**
+- Check script tag references first (most common)
+- Verify component names have hyphens
+- Ensure dependencies are installed
+- Review file paths (use `./` explicitly)
+- Run `tk build` to see full error messages

package/docs/mcp-server.md CHANGED Viewed

@@ -99,6 +99,7 @@ The MCP server exposes the following documentation resources:
 | `tkeron://pre-rendering`         | Transform HTML at build time with .pre.ts files      |
 | `tkeron://cli-reference`         | Complete command-line interface documentation        |
 | `tkeron://best-practices`        | Patterns, anti-patterns, and limitations             |
+| `tkeron://common-issues`         | Troubleshooting guide and common mistakes            |
 | `tkeron://testing`               | How to test tkeron projects with getBuildResult()    |
 ## What AI Agents Can Do
@@ -112,6 +113,7 @@ With access to the MCP server, AI agents can:
 - ✅ Provide accurate CLI commands and options
 - ✅ Debug common issues with components and pre-rendering
 - ✅ Recommend best practices and avoid anti-patterns
+- ✅ **Prevent common mistakes** (script references, component naming, dependencies)
 - ✅ **List and explore example projects**
 - ✅ **Retrieve example code and structures**
 - ✅ **Initialize, build, and develop projects via terminal** (`tk init`, `tk build`, `tk dev`)

package/mcp-server.ts CHANGED Viewed

@@ -71,6 +71,13 @@ const DOCS = [
     description: "Patterns, anti-patterns, and limitations",
     file: "best-practices.md",
   },
+  {
+    uri: "tkeron://common-issues",
+    name: "Common Issues and Solutions",
+    description:
+      "Troubleshooting guide: script references, component naming, dependencies, and common mistakes",
+    file: "common-issues.md",
+  },
   {
     uri: "tkeron://testing",
     name: "Testing Tkeron Projects",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tkeron",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "CLI tool for backend-driven frontend development with TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/buildDir.ts CHANGED Viewed

@@ -33,6 +33,10 @@ export const buildDir = async (
   const files = await buildEntrypoints(htmlFiles, sourceDir, { logger: log });
+  if (!files || !files.artifacts) {
+    throw new Error("Bundle failed");
+  }
   for (const a of files?.artifacts || []) {
     const outPath = join(targetDir, a.pathR);
     if (a.pathR.toLowerCase().endsWith(".html")) {

package/src/buildEntrypoints.ts CHANGED Viewed

@@ -23,44 +23,71 @@ export const buildEntrypoints = async (
     return;
   }
-  const { outputs, success } = await Bun.build({
-    entrypoints: filePaths,
-    minify: true,
-    splitting: false,
-    target: "browser",
-    root,
-    naming: {
-      asset: "[dir]/[name].[ext]",
-      chunk: "[dir]/[name].[ext]",
-      entry: "[dir]/[name].[ext]",
-    },
-  });
+  try {
+    const result = await Bun.build({
+      entrypoints: filePaths,
+      minify: true,
+      splitting: false,
+      target: "browser",
+      root,
+      naming: {
+        asset: "[dir]/[name].[ext]",
+        chunk: "[dir]/[name].[ext]",
+        entry: "[dir]/[name].[ext]",
+      },
+    });
-  if (!success) return;
+    const { outputs, success, logs } = result;
-  const artifacts = await Promise.all(
-    outputs?.map(async (artifact, index) => {
-      const path = artifact.path;
-      const pathR = normalize(artifact.path);
-      const hash = artifact.hash;
-      const kind = artifact.kind;
-      const loader = artifact.loader;
-      const type = artifact.type;
-      const sourcemap = await artifact.sourcemap?.text();
+    if (!success) {
+      if (logs && logs.length > 0) {
+        log.error(`\n❌ Build failed with ${logs.length} error(s):\n`);
+        for (const logEntry of logs) {
+          log.error(`${logEntry.message}`);
+          if (logEntry.position) {
+            log.error(
+              `   at ${logEntry.position.file}:${logEntry.position.line}:${logEntry.position.column}`,
+            );
+          }
+        }
+        log.error("");
+      } else {
+        log.error(`\n❌ Build failed with no error details from Bun.build()`);
+      }
+      return;
+    }
-      return {
-        path,
-        pathR,
-        hash,
-        index,
-        kind,
-        loader,
-        type,
-        sourcemap,
-        artifact,
-      };
-    }),
-  );
+    const artifacts = await Promise.all(
+      outputs?.map(async (artifact, index) => {
+        const path = artifact.path;
+        const pathR = normalize(artifact.path);
+        const hash = artifact.hash;
+        const kind = artifact.kind;
+        const loader = artifact.loader;
+        const type = artifact.type;
+        const sourcemap = await artifact.sourcemap?.text();
-  return { artifacts };
+        return {
+          path,
+          pathR,
+          hash,
+          index,
+          kind,
+          loader,
+          type,
+          sourcemap,
+          artifact,
+        };
+      }),
+    );
+    return { artifacts };
+  } catch (error: any) {
+    log.error(`\n❌ Bun.build() threw an exception:`);
+    log.error(`   ${error.message}`);
+    if (error.stack) {
+      log.error(`\n${error.stack}`);
+    }
+    throw error;
+  }
 };