jac-cl-organization

Organizes multi-component Jac client apps using the stateful-shell architecture and feature-based file layout.

Updated Jul 26, 2026
One-click install
npx skills add https://github.com/PMN123/trapdoor --skill jac-cl-organization-pmn123
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: jac-cl-organization
Source: https://github.com/PMN123/trapdoor/tree/main/.agents/skills/jac-cl-organization
Command: npx skills add https://github.com/PMN123/trapdoor --skill jac-cl-organization-pmn123

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Jac client apps grow messy fast: page files balloon with state and handlers, files get sorted by which machine runs the code instead of what the code is about, and developers reach for hooks or contexts before they are needed. This Skill provides the architectural rules for structuring a multi-component Jac client app so state, files, and shared modules stay organized as the app scales. ## Core Features & Use Cases - Stateful-shell architecture: One page-level component owns all reactive has fields and async handlers, prop-drilling data and Callable callbacks into stateless section components, with handler bodies in the paired .impl.jac annex. - Feature-based file layout: Flat layout for small apps, one folder per feature (client and server code side by side) at 3+ features, with shared/ as a promotion destination rather than a default dump. - Escalation patterns: Clear triggers for when to extract a use<DomainNoun> hook (reused fetch+state logic in 2+ components) versus a createContext/useContext provider (distant components sharing live values). - Use Case: A page file's JSX exceeds 80 lines and several sections share fetching logic — load this Skill to split the page into a shell plus stateless sections, extract a hook, and place files correctly. ## Quick Start Ask the AI to review the growing Jac page component and restructure it into a stateful shell with prop-drilled section components following the jac-cl-organization layout rules.

Frequently Asked Questions about jac-cl-organization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a multi-component Jac client app?

Use the stateful-shell pattern: one page-level component owns all reactive `has` fields and async handlers, then prop-drills data and `Callable` callbacks into stateless section components. Handler bodies live in the paired `.impl.jac` annex file.

When should I use a hook versus a context in Jac?

Extract a hook when the same fetch-plus-state logic recurs in two or more components, since hooks share logic but not state. Use createContext/useContext only when distant components must see the same live values, such as current user or theme.

How should I organize files in a Jac fullstack project?

Keep small apps flat with one file per component. At three or more features, give each feature its own folder holding both client and server code side by side, and move modules to `shared/` only when a second feature imports them.

Why does jac test fail with relative import errors after moving files?

A `..` import climbing out of a feature folder resolves under `jac start` but fails `jac test <file>` because the test runner roots the package at the target file's directory. Server modules across packages must use the no-dot absolute import form.

What happens when I move a Jac module that declares node types?

Moving a module that declares `node` or `edge` types orphans every persisted instance, because archetype identity includes the module path. Graph queries in the moved module silently match nothing, so reorganize before a graph has data or plan a re-ingest.

Do Jac components need cl or sv markers for client placement?

No. A `def:pub` returning JSX in a plain `.jac` file is placed client-side by inference, and referenced helpers follow it into the bundle. The `cl`/`sv`/`na` markers remain available as optional overrides for making boundaries visible.