create-reactra 0.1.0-alpha.0 → 0.1.0-alpha.1

package/index.mjs

@@ -63,6 +63,32 @@ const copyTemplate = (src, dest, tokens) => {
   }
 }
 
+/**
+ * Write the Reactra primer where the common AI coding agents auto-read project
+ * context, so any agent that opens the workspace knows the .tsx files are Reactra
+ * DSL (compiled to React) and won't "fix" them into plain React. Single source —
+ * templates/_agent-primer.md — fanned out to: AGENTS.md (the cross-tool convention,
+ * read by Cursor/Codex/others), .github/copilot-instructions.md (GitHub Copilot),
+ * and CLAUDE.md (Claude Code; imports AGENTS.md so there's one source of truth).
+ */
+const writeAgentContext = (targetDir, name, tokens) => {
+  let primer = readFileSync(join(TEMPLATES, "_agent-primer.md"), "utf8")
+  for (const [k, v] of Object.entries(tokens)) primer = primer.replaceAll(k, v)
+
+  writeFileSync(join(targetDir, "AGENTS.md"), primer)
+
+  mkdirSync(join(targetDir, ".github"), { recursive: true })
+  writeFileSync(join(targetDir, ".github", "copilot-instructions.md"), primer)
+
+  // Claude Code reads CLAUDE.md and resolves `@path` imports — keep it a thin
+  // pointer so the primer has a single source.
+  writeFileSync(
+    join(targetDir, "CLAUDE.md"),
+    `# ${name}\n\nThis project uses **Reactra** (a compiler-first React 19 DSL). ` +
+      `The full agent guide — syntax, the compile pipeline, and good/bad practices — is in AGENTS.md:\n\n@AGENTS.md\n`,
+  )
+}
+
 const main = async () => {
   const opts = parseArgs(argv.slice(2))
   const interactive = stdin.isTTY && !opts.yes
@@ -107,11 +133,11 @@ const main = async () => {
     exit(1)
   }
 
+  const tokens = { __PROJECT_NAME__: name, __REACTRA_VERSION__: VERSIONS.reactra }
+
   mkdirSync(targetDir, { recursive: true })
-  copyTemplate(templateDir, targetDir, {
-    __PROJECT_NAME__: name,
-    __REACTRA_VERSION__: VERSIONS.reactra,
-  })
+  copyTemplate(templateDir, targetDir, tokens)
+  writeAgentContext(targetDir, name, tokens)
 
   if (opts.git) {
     try {
@@ -135,7 +161,8 @@ const main = async () => {
   console.log(`  cd ${name}`)
   if (!opts.install) console.log(`  ${installCmd}`)
   console.log(`  ${devCmd}\n`)
-  console.log("Docs: https://reactra.dev\n")
+  console.log("Docs: https://reactra-docs.vercel.app")
+  console.log("AI agents: AGENTS.md / CLAUDE.md / .github/copilot-instructions.md were added — your editor's AI assistant now knows Reactra.\n")
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-reactra",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Scaffold a new Reactra app — a compiler-first, React-19-compatible framework.",
   "type": "module",
   "bin": {

package/templates/_agent-primer.md

@@ -0,0 +1,82 @@
+# Reactra — guide for AI coding agents
+
+This project uses **Reactra**, a compiler-first framework for React 19. The `.tsx`
+files under `src/` use **Reactra DSL syntax — not plain React**. At build time a
+Vite/Babel plugin compiles the DSL to ordinary React 19 (`useState`,
+`useSyncExternalStore`, `React.use`, `useTransition`, …) with **zero runtime
+framework**. Full docs: <https://reactra-docs.vercel.app>
+
+## ⚠️ Do not "fix" the DSL into plain React
+`export component X { state n = 0; view { … } }` is **valid Reactra**, not broken
+TypeScript. Do **not** convert it to a function component, add `useState`/`useEffect`
+imports, or turn `state`/`derived`/`view` into hooks. Edit *within* the DSL. The
+compiler turns it into the React you'd otherwise hand-write.
+
+## The DSL on one screen
+```reactra
+export component Counter {
+  state count: number = 0           // reactive local state → useState (ephemeral; resets on unmount)
+  derived doubled = count * 2       // computed value; recomputes when inputs change. Read it; never call/assign it.
+  action increment() { count = count + 1 }   // mutate state ONLY inside an action (or a JSX event handler)
+  view {                            // the JSX this component renders
+    <button onClick={increment}>{count} · {doubled}</button>
+  }
+}
+```
+
+**Keywords by scope** — declarations: `component` `store` `service`. Component body:
+`state` `derived` `action` `command` `resource` `effect` `mount` `view` `ref` `meta`
+`uses` `errorBoundary`. Routing: `param` `query` `prefetch` `transition`. Dependency
+injection: `inject` (`inject store` / `inject service`), `provide`, `implements`.
+Store-only: `input`, `preserved state`.
+
+## Async data — `resource` + `await`
+```reactra
+resource user(id) => api.getUser(id)    // the arg list is the dependency (refetch on change); arrow body is the fetcher
+view {
+  await(user) { <Profile data={user.data} /> }
+  pending { <Spinner /> }
+  error(e) { <Err msg={String(e)} /> }
+}
+```
+- The dependency **must be an identifier** (a `state`/`derived`/`param`/`query`/store
+  field) — never a member expression. Alias via `derived` if you need one.
+- Modifiers go **before** `=>`, in any order: `cache`, `swr`, `retry`, `signal`,
+  `select(fn)`. `select(u => u.name)` slices `.data` and re-renders the consumer
+  only when the slice changes.
+
+## Writes — `command`
+The async-write primitive. **Block** form `command save() { … }` → `useActionState`
+(exposes `.pending` / `.result` / `.error`). **Arrow** form `command like() => api.toggle()`
+→ `useTransition`, with optional clauses `optimistic { … }` (instant UI + auto-revert),
+`invalidate [resourceName]` (refetch on success), `rollback(e) { … }` (failure handler).
+
+## Persisting state — use a store, not component `state`
+Component `state` is ephemeral (`useState` — it resets when the route unmounts). To
+share or persist state across navigation, declare a `store` and acquire it:
+```reactra
+inject store cartStore             // bare = subscribe to it
+inject store cartStore({ userId }) // argumented (object literal) = own/instantiate it
+inject service api                 // services require the `service` qualifier
+```
+Stores auto-register on first use; **services are registered in `src/main.tsx` via
+`configureServices(...)`**.
+
+## Good / bad practice
+- **DO** route every `state`/store-field write through an `action` or a JSX event
+  handler. Assigning in `view`/`derived`/`effect`/`mount` is a compile error (R002/R023).
+- **DO** use `derived` for computed values; never call or reassign a `derived`.
+- **DO** put effect teardown in the `return` of `mount` / `effect on(...)` — there is
+  no `cleanup` keyword.
+- **DON'T** pass a freshly-allocated object/array literal as a `resource` dependency
+  (it never cache-equals → refetches every render; warned as R028).
+- **DON'T** write a `key`-less `.map()` inside a `view` (R029).
+
+## Debugging & reference
+- The compiler emits **readable React 19** — to understand a file, read its compiled
+  output, or the DSL⇄compiled examples in the docs.
+- `@reactra/devtools` adds an in-page panel (components, stores, router, time-travel).
+- Error-code prefixes: `R###` component DSL · `S###` store · `RO###` router ·
+  `SVC###` service · `RES###` resource — all searchable in the docs.
+
+**Docs & full keyword reference:** <https://reactra-docs.vercel.app>

package/templates/versions.json

@@ -1,3 +1,3 @@
 {
-  "reactra": "0.1.0-alpha.0"
+  "reactra": "0.1.0-alpha.1"
 }