@qds.dev/code 0.8.2 → 0.9.1

package/README.md

@@ -0,0 +1,102 @@
+# @qds.dev/code
+
+**Interactive code previews and playgrounds for Qwik**
+
+[![npm version](https://img.shields.io/npm/v/@qds.dev/code.svg)](https://www.npmjs.com/package/@qds.dev/code)
+
+## Overview
+
+Documentation with static code examples is hard to learn from. You want to experiment, modify, and see results immediately, but building a live code playground is complex. You need sandboxed execution, bundling, and preview rendering.
+
+**@qds.dev/code** provides a PreviewCompiler class that bundles and executes Qwik code in the browser. Powered by Rolldown WASM for fast bundling, your users can compile code and see instant results without any server setup.
+
+**What makes this different:** Incremental builds. WASM-based bundling for instant feedback. No remote compilation, no cold starts, no server costs.
+
+## Installation
+
+```bash
+npm install @qds.dev/code
+```
+
+**Note:** Typically used in documentation sites, not application code. The WASM bundler adds significant weight (~2MB+). It's recommended to only show the component preview when the user has made the intent they would like to edit code or view a preview.
+
+## Quick Start
+
+**Simplest case:** Compile and run code
+
+```typescript
+import { PreviewCompiler } from '@qds.dev/code/preview';
+import { component$ } from '@qwik.dev/core';
+
+export default component$(() => {
+  const compiler = new PreviewCompiler({
+    deps: {
+      '@qwik.dev/core': './path-to-core-module'
+    }
+  });
+
+  const result = await compiler.compile({
+    srcInputs: {
+      '/src/app.tsx': `export default component$(() => {
+        return <button>Click me</button>;
+      });`
+    }
+  });
+
+  return <div>{/* Render result */}</div>;
+});
+```
+
+**Common pattern:** Browser-based bundling
+
+```typescript
+import { PreviewCompiler } from '@qds.dev/code/preview';
+
+export default component$(() => {
+  const compiler = new PreviewCompiler({
+    deps: {
+      '@qwik.dev/core': './path-to-core-module'
+    }
+  });
+
+  const compile$ = $(async (code: string) => {
+    return await compiler.compile({
+      srcInputs: { '/src/app.tsx': code }
+    });
+  });
+
+  return <div>{/* Use compile$ for interactive editing */}</div>;
+});
+```
+
+## Architecture
+
+For package internals, dependency relationships, and design decisions, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `.` | debug function for development logging |
+| `./preview` | PreviewCompiler class and compilation utilities |
+| `./preview/node` | Server-side helpers for REPL |
+
+## Why This Pattern?
+
+**Browser-based bundling:** We use Rolldown WASM instead of server-side compilation because it eliminates network latency and server costs. Your users get instant feedback. No waiting for compilation, no server to configure or maintain.
+
+**Component isolation:** Previews run in sandboxed iframes, isolated from your main application. This prevents code in previews from affecting your documentation site's state or styles. Users can experiment freely without breaking anything.
+
+## Related Packages
+
+**Depends on:**
+- [@rolldown/browser](https://www.npmjs.com/package/@rolldown/browser) - WASM bundler for in-browser compilation
+
+**Used by:**
+- QDS documentation site - Powers all interactive code examples
+
+## Known Limitations
+
+- **Bundle size:** The WASM bundler adds significant weight (~2MB+ for Rolldown). This package is designed for documentation sites where rich interactivity justifies the cost, not for production applications.
+- **Documentation only:** Not intended for production apps. The bundle size and browser-based compilation are optimized for learning environments.
+- **Modern browsers:** Requires WebAssembly and modern JavaScript features (ES2020+). Won't work in IE11 or older browsers.