@jacare/cli

Command-line tool to create, develop, build, and check Jacaré applications.

Jacaré is a fine-grained reactive UI framework with no Virtual DOM. This CLI wraps Vite and the Jacaré compiler so you can start a project in seconds. jacare check also validates template contracts across parent/child .jcr files (required props, model + bind-*, pulses, emits).

Table of contents

• Install
• Quick start
• Commands
• Create a project
• Development server
• Production build
• Compile a single file
• Check all files
• Project structure
• Configuration
• Templates
• TypeScript support
• Troubleshooting
• Links

Install

Global install

npm install -g @jacare/cli

Then use the jacare command anywhere:

jacare new my-app
jacare dev

Local install (recommended for projects)

npm install -D @jacare/cli

{
  "scripts": {
    "dev": "jacare dev",
    "build": "jacare build",
    "check": "jacare check"
  }
}

Without installing

npx @jacare/cli new my-app
npx @jacare/cli dev

Quick start

jacare new my-shop --template=todo
cd my-shop
npm install
jacare dev

Open http://localhost:3000 — the dev server starts with hot reload for .jcr files.

Commands

| Command | Description | |---------|-------------| | jacare new <name> | Scaffold a new project | | jacare dev | Start the Vite dev server | | jacare build | Production build to dist/ | | jacare compile <file> | Compile one .jcr file to JS | | jacare check | Compile-check all .jcr files | | jacare check --routes | Same + static jacare-go vs createNav screens | | jacare why <file.jcr:line> | Static Binding IR sites for a template line | | jacare bake | Static HTML per route → dist-bake/ (bake.routes in config) | | jacare help | Show help |

Vite-based templates

These use vite, vite build, and vite preview instead of jacare dev:

| Template | Description | |----------|-------------| | vite-minimal | Single-page counter | | vite-nav | Multi-page with routing | | vite-todo | Todo app with devtools |

jacare new my-app --template=vite-minimal
npm create jacare@latest my-app -- --template vite-nav

Create a project

jacare new <name> [--template=minimal|nav|todo|vite-minimal|vite-nav|vite-todo]

Examples

jacare new hello-world
jacare new my-blog --template=nav
jacare new my-shop --template=todo

What gets created

my-app/
  src/
    app.jcr          # or shell.jcr + pages/ for nav/todo
    boot.js          # entry point
  index.html
  public/
  package.json
  jacare.config.js
  jacare.d.ts

After creation:

cd my-app
npm install    # or yarn install
jacare dev

Development server

jacare dev [--port=3000] [--open=false]

| Flag | Default | Description | |------|---------|-------------| | --port | 3000 (or jacare.config.js) | Dev server port | | --open | true | Open browser on start |

Examples

jacare dev
jacare dev --port=4000
jacare dev --open=false

The dev server uses Vite with @jacare/vite-plugin. Changes to .jcr files hot-reload instantly.

Production build

jacare build

Output goes to dist/:

dist/
  index.html
  assets/
    index-abc123.js
    index-def456.css

Serve dist/ with any static host (Netlify, Vercel, GitHub Pages, nginx, etc.).

GitHub Pages

Set the base path in jacare.config.js:

export default {
  title: 'My App',
  base: '/my-repo/',
}

Compile a single file

Compile one .jcr file without Vite:

jacare compile src/app.jcr
jacare compile src/app.jcr dist/app.js
jacare compile src/app.jcr --watch

| Argument | Description | |----------|-------------| | <file.jcr> | Input file (required) | | [output.js] | Output path (optional — defaults to same name with .js) | | --watch | Recompile on file changes |

Useful for inspecting compiler output or integrating with custom pipelines.

Check all files

Validate every .jcr file in the project without building:

jacare check
jacare check --bindings
jacare check --routes
jacare why src/Shop.jcr:12
jacare bake

ok src/app.jcr
ok src/pages/about.jcr
ok src/pages/home.jcr

3 file(s) ok

Compile errors print file:line:column plus a source snippet (^ under the bad token).

jacare check compiles each module and cross-checks parents against child template contracts:

• unknown props / emits
• missing required props and pulse props
• model: true props must use bind-name (not :name)
• soft static type checks (boolean / number / object)
• soft URL-attr warnings when dynamic href / src / … lack safeUrl(...)

jacare check --routes (opt-in) also scans createNav({ screens }) keys and static jacare-go="/…" targets. Dynamic links are skipped; unmatched literals fail CI.

jacare bake (opt-in) writes static HTML per bake.routes in jacare.config.js → dist-bake/.

Exit code 1 if any compile, contract, or (with --routes) route issue is found — ready for CI:

- run: npm install
- run: npx jacare check
- run: npx jacare check --routes

Project structure

Minimal app (single page)

src/
  app.jcr       # UI + state
  boot.js       # mounts app.jcr
index.html
public/
jacare.config.js

App with navigation

src/
  shell.jcr     # layout with <main jacare-frame>
  pages/
    home.jcr
    about.jcr
    not-found.jcr
  nav.js        # createNav() screen map
  boot.js       # nav.attach()
index.html

boot.js example

import App from './app.jcr'

const root = document.getElementById('app')
App(root)

boot.js with navigation

import { nav } from './nav.js'

let disposeDevtools = null
if (import.meta.env.DEV) {
  const { connectJacareDevtools } = await import('@jacare/devtools')
  disposeDevtools = connectJacareDevtools()
}

const root = document.getElementById('app')
let dispose = nav.attach(root)

if (import.meta.hot) {
  import.meta.hot.accept()
  import.meta.hot.dispose(() => {
    disposeDevtools?.()
    disposeDevtools = null
    dispose?.()
    dispose = null
  })
}

Configuration

jacare.config.js in the project root:

export default {
  title: 'My App',   // page title (injected into index.html)
  port: 3000,        // default dev server port
  base: '/',         // Vite base path for deployment
}

The CLI reads this file for dev and build. You can override the port with --port.

Templates

| Template | Dev command | Description | |----------|-------------|-------------| | minimal | jacare dev | Single-page counter app | | nav | jacare dev | Multi-page app with routing, lazy loading, and shell layout | | todo | jacare dev | Full todo app with forms, filters, devtools, and nav | | vite-minimal | vite | Same as minimal, standard Vite scripts | | vite-nav | vite | Same as nav, standard Vite scripts | | vite-todo | vite | Same as todo, standard Vite scripts |

minimal

A simple counter to understand pulses and templates.

nav

Includes:

• shell.jcr with jacare-frame
• nav.js with createNav() and lazy screens
• jacare-go / jacare-here link helpers
• 404 page

todo

Everything in nav, plus:

• Form handling with createForm()
• Filtered lists with #for
• @jacare/devtools integration
• Logo asset in public/

TypeScript support

Scaffolded projects include jacare.d.ts for .jcr module imports.

You can also write TypeScript for Jacaré modules:

• Sibling Foo.jcr.ts — typed logic auto-merged into Foo.jcr
• Pragma // @jacare-ts — type annotations inside the .jcr script (stripped at compile)
• Normal import from .ts files (Vite)

declare module '*.jcr' {
  export function mount(
    target: HTMLElement,
    props?: Record<string, unknown>,
  ): () => void
  export function render(
    props?: Record<string, unknown>,
  ): { html: string; state: unknown }
  export function resume(
    target: HTMLElement,
    state: unknown,
  ): () => void
  const _default: typeof mount
  export default _default
}

Add "checkJs": true in jsconfig.json for type checking in .js files. Details: docs/syntax.md § TypeScript.

Troubleshooting

Port already in use

jacare dev --port=4000

Or change port in jacare.config.js.

Directory already exists

jacare new refuses to overwrite. Choose a different name or remove the existing folder.

Compile errors

Run jacare check to see all errors at once. Each error shows file, line, and a source snippet.

Module not found: @jacare/core

Run npm install in the project directory after jacare new.

Links

• npm — @jacare/cli
• Repository
• Live demo
• Jacaré Lab
• Jacaré UI — @jacare/ui component library
• Syntax guide
• Example todo app
• Related: @jacare/core · @jacare/compiler · @jacare/vite-plugin · @jacare/devtools · @jacare/meta · @jacare/ui

License

MIT