Jacaré

Official language support for Jacaré .jcr files — syntax highlighting, compile diagnostics, Mesh hover, snippets, file icons, and editor ergonomics for the Jacaré reactive UI framework.

Publisher: heberalmeida
Extension ID: heberalmeida.jacare
Author: Heber Almeida
Marketplace: https://marketplace.visualstudio.com/items?itemName=heberalmeida.jacare
Live Lab: https://jacarejs.github.io/core/lab/

Features

Installation

Visual Studio Marketplace

1. Open the Extensions panel (Cmd+Shift+X / Ctrl+Shift+X)
2. Search for Jacaré
3. Install Jacaré by heberalmeida

Or install from the command line:

code --install-extension heberalmeida.jacare

From source (monorepo)

cd packages/vscode-jacare
yarn install
yarn build
yarn package
code --install-extension jacare-0.0.23.vsix --force

Development mode

1. Open the packages/vscode-jacare folder in VS Code
2. Run Run Extension from the Debug panel (F5)
3. A new Extension Development Host window opens with the extension loaded

Snippets

In a .jcr file, type a prefix and accept the suggestion (Tab / Enter). Snippets use the jacare language id.

Navigation snippets (.js / .ts)

Pair jcr-screen in the .jcr page with jcr-nav-lazy in nav.js.

Lab command

Command Palette → Jacaré: Open Lab Lesson for Symbol

• Cursor on a known symbol (pulse, #if, createNav, bind-value, …) → opens that Lab lesson
• Otherwise → QuickPick of all lessons

Live Lab: https://jacarejs.github.io/core/lab/

Template expression style

Both forms are reactive. Prefer the bare call when nothing from a #for (or other local) needs capturing:

${cart.count()}
${t('home.lead')}
class-on=${open()}

Use an arrow when the expression must close over a loop item or handler argument:

#for items() as item (item.id)
  <span>${() => label(item.id)}</span>
  <button on-click=${() => remove(item.id)}>×</button>
#end

jacare check warns on redundant nullary arrows (--strict-style to fail CI). See syntax — Template bindings.

Snippet examples

Component scaffold (jcr-component):

export <contract>
  props: {
    label: { type: 'string', required: true }
  }
  emits: ['change']
</contract>

export <view>
  <div class="component">
    
  </div>
</view>

export <style>
.component {
  
}
</style>

Contract (jcr-contract):

export <contract>
  props: {
    label: { type: 'string', required: true }
  }
  pulses: {
    count: 'number'
  }
  slots: ['default', 'actions']
  emits: ['change']
</contract>

Pulse bag (jcr-bag) / Mesh sugar (jcr-mesh) / Contract links (jcr-links):

export const cart = createBag('cart', () => { /* … */ })

export <view>
  <span>${@cart/count}</span>
</view>

Island host (jcr-island):

import { mountIsland } from '@jacare/core/island'
import Widget from './Widget.jcr'

const dispose = mountIsland('#slot', Widget, {
  props: { start: 0 },
  shadow: true,
})

Control flow (jcr-if, jcr-for):

#if show()
  <p>Visible</p>
#else
  <p>Hidden</p>
#end

#for items() as item (item.id)
  <li>${item.label}</li>
#end

Tab through placeholders to fill names, types, and handlers.

Language support

File extension

Jacaré files are plain JavaScript modules. The extension highlights both the script and embedded templates.

Highlighted syntax

JavaScript module

Tagged template

import { signal, view } from '@jacare/core'

const count = signal(0)

function increment() {
  count.update((n) => n + 1)
}

export default view`
  <div class="counter">
    <p>${count}</p>
    <button on-click=${increment}>+1</button>
  </div>
`

View block (HTML-style alternative)

import { signal } from '@jacare/core'

const count = signal(0)

function increment() {
  count.update((n) => n + 1)
}

export <view>
  <div class="counter">
    <p>${count}</p>
    <button on-click=${increment}>+1</button>
  </div>
</view>

Template contracts

Declare the component surface with export <contract>. The compiler checks parents with jacare check (and Vite transform) — no runtime PropTypes. Use bind-value for model: true props; :value is rejected.

export <contract>
  props: { label: 'string' }
  pulses: { count: 'number' }
  slots: ['default', 'actions']
  emits: ['inc']
</contract>

export <view>
  <p>${label}: ${count}</p>
  <slot name="actions" />
  <button on-click=${() => emit('inc')}>+</button>
</view>

Parent usage (validated at check time):

<Counter :label=${'Score'} :count=${score} on-inc=${() => score.update((n) => n + 1)}>
  <button slot="actions">Reset</button>
</Counter>

See the API — Template contracts and Pulse bags sections for the full reference.

Pulse Mesh (shared state)

Jacaré-native shared pulses — highlight and snippets for bags, contract links, and ${@bag/key} address sugar.

import { createBag, pulse, ripple } from '@jacare/core'

export const cart = createBag('cart', () => {
  const count = pulse(0)
  return { count, bump: () => ripple(() => count.update((n) => n + 1)) }
})

export <view>
  <span>${cart.count}</span>
  <span>${@cart/count}</span>
  <button type="button" on-click=${@cart/bump}>+</button>
</view>

export <contract>
  links: {
    count: { from: 'cart.count', mode: 'read' }
  }
</contract>

export <view>
  <span>${count}</span>
</view>

Template directives

view`
#if show()
  <p>Visible</p>
#else
  <p>Hidden</p>
#end

#for items() as item (item.id)
  <li>${item.label}</li>
#end
`

Components and slots

view`
<Card :title=${title}>
  <p>Slot content</p>
</Card>
`

Scoped styles

export <style>
.card { padding: 1rem; }
.title { font-weight: bold; }
</style>

Scope names (for theme authors)

TypeScript coloring

Optional color themes (Preferences: Color Theme):

• Jacaré scopes (dark) — accent for @jacare-ts, directives, tags, mesh
• Jacaré scopes (light) — same scopes for light UI

Snippets: jcr-ts (pragma scaffold) · jcr-ts-sibling in .jcr.ts files.

File icons

The extension contributes the Jacaré Icons file icon theme and sets it as the default when installed.

If icons do not appear:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run Preferences: File Icon Theme
3. Select Jacaré Icons
4. Run Developer: Reload Window

Configuration

The extension works out of the box. No settings are required.

To use another file icon theme while keeping syntax highlighting, pick any theme in Preferences: File Icon Theme. Language highlighting for .jcr files remains active.

Recommended workspace settings

Optional settings.json for Jacaré projects:

{
  "files.associations": {
    "*.jcr": "jacare"
  },
  "editor.quickSuggestions": {
    "strings": true
  }
}

What this extension does not include

Related documentation

• Jacaré repository
• API reference — template contracts · Pulse bags / Mesh
• Jacaré Lab — interactive demos including Pulse bags
• Main README
• Syntax guide
• Live demos — Todo · Showcase · Scale BMI · Lab
• Compiler docs

License

MIT © Heber Almeida