module-tsx 0.0.0 → 0.0.2

package/README.md

@@ -0,0 +1,95 @@
+# module-tsx
+
+Run TypeScript (and React) modules directly in the browser, without a build step.
+
+## Usage
+
+```html
+<!-- Load this library -->
+<script type="module" src="https://esm.sh/module-tsx"></script>
+
+<div id="root"></div>
+
+<!-- Write your TypeScript/TSX inline -->
+<script type="module-tsx">
+  import React from "react"; // bare specifier → https://esm.sh/react
+  import { createRoot } from "react-dom/client";
+  import App from "./src/App.tsx"; // relative imports are fetched and compiled on the fly
+
+  const root = document.getElementById("root") as HTMLDivElement;
+  createRoot(root).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+</script>
+
+<!-- OR load an external file -->
+<script type="module-tsx" src="./main.tsx"></script>
+```
+
+You publish the **source code**, and users can run it directly in the browser **without any build step**.
+
+```tsx
+// src/App.tsx
+export default function App() {
+  return <div>Hello, module-tsx!</div>;
+}
+```
+
+## Features
+
+- **TypeScript & JSX/TSX** — transpiled on the fly using the TypeScript compiler
+- **Bare specifier resolution** — `import "react"` is automatically rewritten to a CDN URL (defaults to `https://esm.sh/`)
+- **Relative imports** — `.ts`/`.tsx` files are fetched and compiled recursively
+- **CSS imports** — `import "./style.css"` injects a `<style>` tag; `import "./style.module.css"` returns a CSS Modules object
+- **Import map support** — respects `<script type="importmap">` on the page for specifier overrides
+- **Auto React import** — JSX is detected and `import React from "react"` is injected automatically if missing
+
+## Programmatic API
+
+```ts
+import { ModuleTSX } from "module-tsx";
+
+const m = new ModuleTSX({
+  baseUrl: location.href, // base for resolving relative specifiers
+  importMap: { imports: { react: "https://esm.sh/react" } }, // merged with page importmaps
+  resolveBareSpecifier: "https://cdn.jsdelivr.net/npm/", // string prefix or function
+});
+
+// Import a module by specifier
+const react = await m.import("react");
+const app = await m.import("./app.tsx");
+
+// Import from an in-memory string
+const { x } = await m.importCode(document.location.href, `export const x: number = 1`);
+
+// Events
+m.addEventListener("import", (e) => console.log("loading", e.detail.id));
+m.addEventListener("import:error", (e) => console.error("failed", e.detail.id, e.detail.error));
+m.addEventListener("transform", (e) => console.log("compiling", e.detail.sourceUrl));
+m.addEventListener("transform:error", (e) => console.error("compile error", e.detail.sourceUrl, e.detail.error));
+```
+
+## Use with AI
+
+module-tsx is well-suited for AI-generated pages — an AI can produce a single, self-contained HTML file that runs TypeScript and React directly in the browser with no build step or configuration.
+
+To use the skill, run
+
+```sh
+npx skills add yieldray/module-tsx
+```
+
+## CDN
+
+```html
+<!-- ESM -->
+<script type="module" src="https://esm.sh/module-tsx"></script>
+
+<!-- ESM (self-contained, no external dependencies) -->
+<script type="module" src="https://raw.esm.sh/module-tsx/dist/index.mjs"></script>
+
+<!-- UMD (exposes window.ModuleTSX) -->
+<script src="https://raw.esm.sh/module-tsx/dist/index.umd.js"></script>
+```

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+//#region src/importmap.d.ts
+type ModuleSpecifierMap = Map<string, URL | null>;
+interface SpecifierResolutionRecord {
+  serializedBaseURL: string;
+  specifier: string;
+  specifierAsURL: URL | null;
+}
+declare class ImportMap {
+  imports: ModuleSpecifierMap;
+  scopes: Map<string, ModuleSpecifierMap>;
+  integrity: Map<string, string>;
+  constructor(imports?: ModuleSpecifierMap, scopes?: Map<string, ModuleSpecifierMap>, integrity?: Map<string, string>);
+  /** Parse a JSON import map string against a base URL. */
+  static parse(input: string, baseURL: URL | string): ImportMap;
+  /** Build an ImportMap from a plain object (same shape as the JSON format). */
+  static of(json: object, baseURL: URL | string): ImportMap;
+  /** Merge newImportMap into oldImportMap in place (spec § "merge existing and new import maps"). */
+  static merge(oldImportMap: ImportMap, newImportMap: ImportMap, resolvedModuleSet?: ReadonlyArray<SpecifierResolutionRecord>): void;
+  /** Resolve a specifier against an import map (spec § "resolve a module specifier"). */
+  static resolve(specifier: string, importMap: ImportMap, baseURL: string | URL): {
+    url: string;
+    record: SpecifierResolutionRecord;
+  } | undefined;
+  /** Parse all <script type="importmap"> elements from the DOM. */
+  static fromDOM(): ImportMap;
+}
+//#endregion
+//#region src/module-tsx.d.ts
+interface ModuleTSXConfig {
+  /**
+   * The base URL to resolve relative module specifiers.
+   * This is typically the URL of the main script or the HTML page.
+   */
+  baseUrl?: string;
+  fetch?: (fullURL: string) => Promise<Response>;
+  importMap?: ImportMap;
+  /**
+   * Given a bare specifier, return a full URL to load the module.
+   * This can be used to convert for example import "react" to import "https://esm.sh/react".
+   * If not provided, it will default to using "https://esm.sh/" as the base URL for bare specifiers.
+   * @default "https://esm.sh/"
+   */
+  resolveBareSpecifier?: string | ((specifier: string) => string);
+}
+interface ModuleTSXEventMap {
+  /** Fired when an import starts. `id` is the original specifier as passed by the caller. */
+  import: CustomEvent<{
+    id: string;
+  }>;
+  /** Fired when an import fails. `id` is the specifier at the point of failure. */
+  "import:error": CustomEvent<{
+    id: string;
+    error: any;
+  }>;
+  /** Fired when a source file starts being transpiled. */
+  transform: CustomEvent<{
+    sourceUrl: string;
+  }>;
+  /** Fired when transpilation fails. */
+  "transform:error": CustomEvent<{
+    sourceUrl: string;
+    error: any;
+  }>;
+}
+interface IModuleTSX extends EventTarget {
+  addEventListener<T extends keyof ModuleTSXEventMap>(type: T, listener: (this: ModuleTSX, ev: ModuleTSXEventMap[T]) => any, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+declare class ModuleTSX extends EventTarget implements IModuleTSX {
+  readonly baseUrl: string;
+  readonly importMap: ImportMap;
+  readonly fetch: (url: string) => Promise<Response>;
+  readonly resolveBareSpecifier: (specifier: string) => string;
+  private readonly resolvedModuleSet;
+  private readonly sourceTracker;
+  private readonly fetchText;
+  constructor(config?: ModuleTSXConfig);
+  /** Add a new import map, merging it into the existing one per the spec.
+   *  Rules that conflict with already-resolved modules are silently dropped. */
+  addImportMap(newImportMap: ImportMap): void;
+  private emit;
+  import(id: string, options?: any): Promise<any>;
+  importCode(sourceUrl: string, code: string, options?: any): Promise<any>;
+  /** Transform module source code and return a blob URL with the transformed content */
+  private transformSourceModule;
+  private getLoaderByResourceType;
+  private tsxLoader;
+  private resolveLocalUrl;
+  private resolveSpecifier;
+  private resolveSpecifiers;
+}
+//#endregion
+//#region src/error.d.ts
+/** Custom error class for module-tsx */
+declare class ModuleTSXError extends Error {
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * The singleton global instance of ModuleTSX.
+ */
+declare const instance: ModuleTSX;
+//#endregion
+export { ImportMap, ModuleTSX, ModuleTSXError, instance };