ember-live-compiler 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Kulakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,25 +1,114 @@
 # ember-live-compiler
 
-> **Status: 0.0.1 — scaffold only.** The public surface is being extracted from
-> [`vite-plugin-ember`](../vite-plugin-ember). Today only `createOwner` is
-> implemented; the build-time and runtime compile pipelines land in 0.1.
+> Bundler-agnostic engine for compiling and rendering `.gjs` / `.gts` Ember
+> components. Extracted from [`vite-plugin-ember`](../vite-plugin-ember) so the
+> same core can power live Ember demos in any docs/preview stack.
 
-A bundler-agnostic engine for compiling and rendering `.gjs` / `.gts` Ember
-components. It will be the shared core that powers live Ember demos in:
+[![npm](https://img.shields.io/npm/v/ember-live-compiler.svg)](https://www.npmjs.com/package/ember-live-compiler)
+[![license](https://img.shields.io/npm/l/ember-live-compiler.svg)](./LICENSE)
 
-- VitePress (via `vite-plugin-ember`)
-- Docusaurus (via `docusaurus-plugin-ember`, planned)
-- Storybook (after [storybookjs/storybook#33048](https://github.com/storybookjs/storybook/pull/33048))
-- Backstage TechDocs (via a runtime-only addon, planned)
-- [kolay](https://github.com/universal-ember/kolay) and `ember-cli-addon-docs` (as a shared dependency, planned)
+## Why
+
+Every "live Ember demo" tool needs the same two pieces: a Babel + content-tag
+pipeline at build time, and a minimal owner + renderer at runtime. Until now
+those lived inside `vite-plugin-ember`. This package lifts them out so the
+ecosystem can share one implementation:
+
+- VitePress — via [`vite-plugin-ember`](../vite-plugin-ember)
+- Docusaurus — via `docusaurus-plugin-ember` (planned)
+- Storybook — after [storybookjs/storybook#33048](https://github.com/storybookjs/storybook/pull/33048)
+- Backstage TechDocs — runtime-only addon (planned)
+- [kolay](https://github.com/universal-ember/kolay), `ember-cli-addon-docs` — as a shared dependency (planned)
+
+## Install
+
+```sh
+npm install ember-live-compiler
+# peer (optional, only needed for runtime/render):
+npm install ember-source
+```
+
+`ember-source >= 6.8.0` is declared as an optional peer — required only if you
+call `render()`, since it dynamically imports `@ember/renderer`.
 
 ## Subpath exports
 
-| Import                         | Environment | Purpose                                               |
-| ------------------------------ | ----------- | ----------------------------------------------------- |
-| `ember-live-compiler`          | Node        | Build-time `compile()` for bundler plugins.           |
-| `ember-live-compiler/runtime`  | Browser     | In-browser `compile()` + `render()`.                  |
-| `ember-live-compiler/resolver` | Both        | Pure helpers for resolving `@ember/*` / `@glimmer/*`. |
+| Import                         | Environment   | Purpose                                                        |
+| ------------------------------ | ------------- | -------------------------------------------------------------- |
+| `ember-live-compiler`          | Node          | Build-time `createNodeCompiler()` — Babel + content-tag.       |
+| `ember-live-compiler/runtime`  | Browser       | `render()` + `createOwner()` for mounting compiled components. |
+| `ember-live-compiler/resolver` | Node, Browser | Pure helpers for resolving `@ember/*` / `@glimmer/*`.          |
+
+## Node — build-time compile
+
+```ts
+import { createNodeCompiler } from 'ember-live-compiler';
+
+const compiler = createNodeCompiler({
+  // Optional: pass a pre-loaded ember-template-compiler, or a path to one
+  templateCompiler: {
+    compilerPath: 'ember-source/dist/ember-template-compiler.js',
+  },
+  babelPlugins: [],
+  babelPresets: [],
+  parserPlugins: [],
+});
+
+const { code, map } = await compiler.compile(source, {
+  filename: 'demo.gjs',
+  kind: 'gjs', // 'gjs' | 'gts' | 'precompiled-template'
+  sourceMaps: true,
+});
+```
+
+Wrap it in a Vite / Rollup / esbuild / Webpack plugin and you've got Ember SFC
+support.
+
+## Browser — render
+
+```ts
+import { render } from 'ember-live-compiler/runtime';
+import * as DemoModule from './demo.gjs';
+
+const mount = await render(DemoModule, {
+  into: document.getElementById('preview')!,
+});
+
+// later
+mount.destroy();
+```
+
+`render()` lazily imports `@ember/renderer` (Ember 6.8+) so apps that never
+call it don't pay the import cost. The host bundler must be able to resolve
+`@ember/*` specifiers — `vite-plugin-ember`'s `resolveId` hook and
+`ssr.noExternal` rule already handle this; equivalent wiring is needed for
+other bundlers.
+
+## Resolver helpers
+
+For bundler authors who need to wire up `@ember/*` resolution themselves:
+
+```ts
+import {
+  EMBER_PACKAGE_PREFIXES,
+  EMBROIDER_MACROS_VIRTUAL_ID,
+  EMBROIDER_MACROS_SHIM_SOURCE,
+  isEmberSpecifier,
+} from 'ember-live-compiler/resolver';
+```
+
+Pure, bundler-free. No I/O, no Babel, safe to import from anywhere.
+
+## Status
+
+`0.1.x` — public but pre-stable. The Node compile pipeline and runtime
+`render()` are exercised in production by `vite-plugin-ember`'s VitePress
+docs. Planned for upcoming minors:
+
+- `compile()` in `runtime` (lazy `@babel/standalone` + content-tag wasm) for
+  fully in-browser source → component.
+- Stable 1.0 once at least one additional bundler integration ships against
+  the engine.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-live-compiler",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Bundler-agnostic engine for compiling and rendering .gjs/.gts Ember components — the core that powers live Ember demos in VitePress, Docusaurus, Storybook, Backstage TechDocs, kolay, and more.",
   "keywords": [
     "ember",
@@ -46,18 +46,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "format": "prettier . --cache --write",
-    "format:check": "prettier . --cache --check",
-    "lint": "concurrently 'pnpm:lint:*(!fix)' --names 'lint:'",
-    "lint:fix": "concurrently 'pnpm:lint:*:fix' --names 'fix:'",
-    "lint:format": "prettier . --cache --check",
-    "lint:format:fix": "prettier . --cache --write",
-    "lint:js": "eslint .",
-    "lint:js:fix": "eslint . --fix",
-    "lint:types": "tsc --noEmit"
-  },
   "dependencies": {
     "@babel/core": "^7.29.0",
     "@babel/plugin-transform-typescript": "^7.28.6",
@@ -86,5 +74,17 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier . --cache --write",
+    "format:check": "prettier . --cache --check",
+    "lint": "concurrently 'pnpm:lint:*(!fix)' --names 'lint:'",
+    "lint:fix": "concurrently 'pnpm:lint:*:fix' --names 'fix:'",
+    "lint:format": "prettier . --cache --check",
+    "lint:format:fix": "prettier . --cache --write",
+    "lint:js": "eslint .",
+    "lint:js:fix": "eslint . --fix",
+    "lint:types": "tsc --noEmit"
   }
 }