Katachi

Katachi lets you author template-like components once in restricted TSX and compile them to multiple outputs.

Today it can emit:

• React TSX components
• static-oriented TSX components
• Askama Rust wrapper files that reference generated include files
• Askama include partials
• Liquid templates
• Liquid snippets

Katachi is still early, but it is already usable if you need one component source that can target both React-style environments and Askama.

Getting Started

Try it once without installing it:

pnpm dlx @relevate/katachi build

or:

npx @relevate/katachi build

If you want Katachi in your project, install it:

pnpm add -D @relevate/katachi

or:

npm install --save-dev @relevate/katachi

Then add Katachi's JSX typing layer to tsconfig.json:

{
  "compilerOptions": {
    "jsx": "preserve",
    "types": ["node", "@relevate/katachi/jsx"]
  }
}

If you already use a types array, append @relevate/katachi/jsx instead of replacing your existing entries.

By default, Katachi reads templates from:

src/templates/**/*.template.tsx

Build from your project root:

pnpm exec katachi build

or without installing it first:

pnpm dlx @relevate/katachi build

By default, Katachi writes:

• dist/react
• dist/jsx-static
• dist/askama
• dist/askama/includes
• dist/liquid
• dist/liquid/snippets

If you want custom paths:

pnpm exec katachi build --templates ./katachi/templates --dist ./generated

If you want compact HTML-style output for the generated Askama include and Liquid files:

pnpm exec katachi build --minify

If you only want specific outputs:

pnpm exec katachi build --target react --target liquid

First Template

Start with a normal .template.tsx file:

import { If, type TemplateNode } from "@relevate/katachi";

export type Props = {
  tone: "calm" | "urgent";
  title: string;
  children?: TemplateNode;
};

export default function NoticePanel({ tone, title, children }: Props) {
  return (
    <aside
      className={[
        "rounded-3xl border px-5 py-4",
        tone == "calm" && "border-sky-200 bg-sky-50/80",
        tone == "urgent" && "border-rose-200 bg-rose-50/80",
      ]}
    >
      <h3>{title}</h3>
      <If test={tone == "urgent"}>
        <p>Action recommended</p>
      </If>
      {children}
    </aside>
  );
}

Build it with:

pnpm exec katachi build

That generates target-specific files under dist/.

What Katachi Generates

By default, build output goes to:

• dist/react/**/*.tsx
• dist/jsx-static/**/*.tsx
• dist/askama/**/*.rs
• dist/askama/includes/**/*.html
• dist/liquid/**/*.liquid
• dist/liquid/snippets/**/*.liquid

Nested templates preserve their relative directory layout.

What Katachi Supports Today

• template authoring in src/templates/**/*.template.tsx
• imports between templates
• same-file local helper components
• dynamic class and className arrays
• If
• Else
• For
• top-level doctypes
• raw script and style bodies
• nested components
• React output
• static-oriented TSX output
• Askama output
• Liquid output

TemplateNode is the way to pass pre-authored template content through Katachi. When you render a TemplateNode or children, Katachi keeps it safe for Askama output automatically, so there is no separate safe(...) helper.

Why Katachi Exists

At Relevate, our docs system is built in Rust and renders components with Askama. We also wanted a live editor that could use the same component structure and styling without maintaining a separate hand-written React component library.

Katachi exists to make that possible: one authoring format, multiple outputs.

What Katachi Is Not

• not a full React compiler
• not a full Askama replacement
• not arbitrary JavaScript execution in templates
• not a general-purpose frontend framework

Documentation

• Getting started
• Template syntax
• Target outputs
• Architecture
• Consumer example

Current Limitations

• The TSX input is not arbitrary React.
• Generated React output is valid React, but the input syntax is compiler-owned.
• The repository-level smoke tests build the public example project under examples/basic.

Contributing

If you are working on Katachi itself rather than using it in another project:

• pnpm build
• pnpm verify:examples
• pnpm test
• pnpm typecheck

See CONTRIBUTING.md and docs/architecture.md.

License

MIT. See LICENSE.