tkeron tkeron

Common Issues and Solutions

Script Tag References

"Bundle failed" or Cannot Resolve Module

Problem: HTML references .js but source files are .ts

<!-- WRONG -->
<script src="index.js"></script>

<!-- CORRECT -->
<script type="module" src="index.ts"></script>

Tkeron uses Bun.build() to bundle. Always reference .ts files in HTML — Tkeron compiles .ts → .js and updates the reference.

Component Naming

Component Name Must Contain Hyphen

<!-- WRONG (reserved HTML tag) -->
<header></header>

<!-- CORRECT -->
<app-header></app-header>

Custom elements must contain at least one hyphen. This is a web standard.

File References

Assets Not Found After Build

<!-- Breaks if HTML moves -->
<img src="images/logo.png" />

<!-- Works from any location -->
<img src="./images/logo.png" />

Always use explicit relative paths (./ or ../).

Component Resolution

Component Not Found

Tkeron searches for components in this order:

  1. Same directory as the HTML file
  2. Any subdirectory of websrc/ via glob search (**/${tagName}.com.*)

Components can live in any subdirectory and will be found automatically. The first glob match is used when multiple matches exist.

TypeScript Compilation

Type Errors

Tkeron's TypeScript compilation is transpile-only — it does NOT type-check. Bun's transpiler converts .ts → .js without running the type checker.

For type checking, use your editor or run tsc --noEmit separately.

Use tkeron.d.ts (included in tk init projects) for com autocompletion in .com.ts files. The document variable in .pre.ts files is available through lib: ["DOM"] in the generated tsconfig.json.

Build Performance

Slow Builds

Common AI Agent Mistakes

When AI agents build Tkeron projects:

  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
  5. CLI args: tk build and tk dev — no directory arguments (fixed convention: websrc/ → web/)

Troubleshooting

"Source directory does not exist"

ls websrc              # Check if websrc/ exists
tk init .              # Or initialize project in current dir

"Command not found: tk"

bun install -g tkeron  # Reinstall globally

Port already in use

tk dev 3001            # Use different port

Components not working

Build hangs

  1. Check for infinite loops in .pre.ts or .com.ts
  2. Check for API requests without timeout
  3. Press Ctrl+C and review your code

Next Steps