# Shared modules

> Plain .ts modules hold values, types and pure functions that components share, like design tokens. The compiler copies each into every output tree unchanged.

Shared modules let a design system write its sizes, variant tables and small helpers once, and read them from every component. In Unframework they're plain `.ts` files that need no compiling: the compiler copies each one into every framework's output tree, byte for byte, beside the components that import it. Think of a size table pasted into ten components until one of them gets a new size, a price formatter that each framework's port rounds differently, or a `tokens.ts` that quietly imports React and breaks the Vue build.

This page walks you through what a component may read from a module, and what a shared module may hold. We'll look at:

- **Values from a `.ts` module:** constants, tables and pure functions.
- **The module's own constants:** declarations above the component's function.
- **What a shared module may import:** other modules and packages, and what stays out.
- **When a shared file changes:** the project graph, and what an edit compiles again.

## Values from a `.ts` module

A shared module exports plain values, types and functions:

<!-- prettier-ignore -->
```ts [format.ts]
// Pure helpers shared by components (ADR-0070): each output imports them from its copy of this
// module, and calls them in its template, its derived values and its listeners alike.
export function formatPrice(cents: number): string {
  return `€${(cents / 100).toFixed(2)}`;
}

export function pluralise(count: number, noun: string): string {
  return `${count} ${noun}${count === 1 ? "" : "s"}`;
}
```

A component imports them like any module, and calls them in its template, its derived values and its listeners alike:

<!-- prettier-ignore -->
```tsx [PriceTag.uf.tsx]
import { computed, defineEmits, ref } from "@uxfront/unframework";

import { formatPrice, pluralise } from "./format";

export default function PriceTag({ cents }: { cents: number }) {
  const emit = defineEmits<{ order: [summary: string] }>();
  const quantity = ref(1);
  const total = computed(() => formatPrice(cents * quantity.value));

  function order() {
    emit("order", `${pluralise(quantity.value, "item")} for ${total.value}`);
  }

  return (
    <section class="price-tag" aria-label="Price">
      <p>Each: {formatPrice(cents)}</p>
      <p role="status">
        {pluralise(quantity.value, "item")}: {total.value}
      </p>
      <button type="button" onClick={() => quantity.value++}>
        One more
      </button>
      <button type="button" onClick={order}>
        Order
      </button>
    </section>
  );
}
```

Every output imports the same names from its own copy of `format.ts`, which sits beside it unchanged:

::framework-switcher

#react

<!-- prettier-ignore -->
```tsx [PriceTag.tsx]
import { formatPrice, pluralise } from "./format";
import { type CSSProperties, useMemo, useRef, useState } from "react";

export interface PriceTagEvents {
  onOrder?: (summary: string) => void;
}

export interface PriceTagAttributes {
  className?: string;
  style?: CSSProperties;
}

export default function PriceTag({
  cents,
  onOrder,
  className,
  style,
  ...attributes
}: { cents: number } & PriceTagEvents & PriceTagAttributes) {
  const [quantity, setQuantity] = useState(1);
  const quantityRef = useRef(quantity);
  const total = useMemo(() => formatPrice(cents * quantity), [cents, quantity]);

  function currentTotal() {
    return formatPrice(cents * quantityRef.current);
  }

  function order() {
    onOrder?.(`${pluralise(quantityRef.current, "item")} for ${currentTotal()}`);
  }

  return (
    <section
      className={cx("price-tag", className)}
      aria-label="Price"
      style={style}
      {...scopeAttributes(attributes)}
    >
      <p>Each: {formatPrice(cents)}</p>
      <p role="status">
        {pluralise(quantity, "item")}: {total}
      </p>
      <button
        type="button"
        onClick={() => {
          quantityRef.current++;
          setQuantity(quantityRef.current);
        }}
      >
        One more
      </button>
      <button type="button" onClick={order}>
        Order
      </button>
    </section>
  );
}

/** Joins class names, and the keys of an object's truthy entries, into one `className`. */
function cx(...parts: unknown[]): string {
  const names: string[] = [];
  for (const part of parts) {
    if (typeof part === "string") {
      if (part) names.push(part);
    } else if (part && typeof part === "object") {
      for (const [key, on] of Object.entries(part)) {
        if (on) names.push(key);
      }
    }
  }
  return names.join(" ");
}

/** The scope attributes of the styled parents that render this component, for its root. */
function scopeAttributes(props: object): Record<string, ""> {
  const scope: Record<string, ""> = {};
  for (const key of Object.keys(props)) {
    if (key.startsWith("data-uf-")) scope[key] = "";
  }
  return scope;
}
```

#vue

<!-- prettier-ignore -->
```vue [PriceTag.vue]
<script setup lang="ts">
import { formatPrice, pluralise } from "./format";
import { computed, ref } from "vue";

const { cents } = defineProps<{ cents: number }>();
const emit = defineEmits<{ order: [summary: string] }>();

const quantity = ref(1);
const total = computed(() => formatPrice(cents * quantity.value));

function order() {
  emit("order", `${pluralise(quantity.value, "item")} for ${total.value}`);
}
</script>

<template>
  <section class="price-tag" aria-label="Price">
    <p>Each: {{ formatPrice(cents) }}</p>
    <p role="status">{{ pluralise(quantity, "item") }}: {{ total }}</p>
    <button type="button" @click="quantity++">One more</button>
    <button type="button" @click="order">Order</button>
  </section>
</template>
```

#svelte

<!-- prettier-ignore -->
```svelte [PriceTag.svelte]
<svelte:options runes={true} preserveWhitespace={false} />

<script lang="ts">
  import { formatPrice, pluralise } from "./format";
  import type { ClassValue } from "svelte/elements";

  type Props = {
    cents: number;
    onorder?: (summary: string) => void;
    class?: ClassValue;
    style?: string;
  };

  let { cents, onorder, class: className, style, ...attributes }: Props = $props();

  let quantity = $state(1);
  const total = $derived(formatPrice(cents * quantity));

  function order() {
    onorder?.(`${pluralise(quantity, "item")} for ${total}`);
  }

  /** The scope attributes of the styled parents that render this component, for its root. */
  function scopeAttributes(props: object): Record<string, ""> {
    const scope: Record<string, ""> = {};
    for (const name of Object.keys(props)) if (name.startsWith("data-uf-")) scope[name] = "";
    return scope;
  }
</script>

<section
  class={["price-tag", className]}
  aria-label="Price"
  {style}
  {...scopeAttributes(attributes)}
>
  <p>Each: {formatPrice(cents)}</p
  ><p role="status">{pluralise(quantity, "item")}: {total}</p
  ><button type="button" onclick={() => quantity++}>One more</button
  ><button type="button" onclick={order}>Order</button>
</section>
```

#angular

<!-- prettier-ignore -->
```ts [price-tag.ts]
import { formatPrice, pluralise } from "./format";
import {
  Component,
  Directive,
  ElementRef,
  type OnInit,
  Renderer2,
  computed,
  inject,
  input,
  output,
  signal,
} from "@angular/core";

/** The scope attributes taken off each host, for the roots its component renders later. */
const scopes = new WeakMap<Element, string[]>();

/**
 * Gives a root node of its component the scope attributes the component's styled parents put on
 * its host (ADR-0063), and takes them off the host, which keeps only `display: contents`.
 */
@Directive({ selector: "[ufScope]" })
export class ScopeAttributes implements OnInit {
  readonly ufScope = input.required<HTMLElement>();
  private readonly element = inject<ElementRef<Element>>(ElementRef);
  private readonly renderer = inject(Renderer2);

  ngOnInit(): void {
    const host = this.ufScope();
    let names = scopes.get(host);
    if (!names) {
      names = host.getAttributeNames().filter((name) => name.startsWith("data-uf-"));
      for (const name of names) this.renderer.removeAttribute(host, name);
      scopes.set(host, names);
    }
    for (const name of names) this.renderer.setAttribute(this.element.nativeElement, name, "");
  }
}

@Component({
  selector: "uf-price-tag",
  imports: [ScopeAttributes],
  host: { "[attr.class]": "null", "[attr.style]": "'display: contents;'" },
  preserveWhitespaces: false,
  template: `
    @let cents = this.cents();
    @let quantity = this.quantity();
    @let total = this.total();
    <section
      class="price-tag"
      aria-label="Price"
      [class]="this.class()"
      [style]="this.style()"
      [ufScope]="this.host"
    >
      <p>Each: {{ formatPrice(cents) }}</p>
      <p role="status">{{ pluralise(quantity, "item") }}: {{ total }}</p>
      <button type="button" (click)="onOneMore()">One more</button>
      <button type="button" (click)="onOrder()">Order</button>
    </section>
  `,
})
export default class PriceTag {
  readonly cents = input.required<number>();
  readonly class = input<string>();
  readonly style = input<Record<string, string | null | undefined>>();
  readonly order = output<string>();
  protected readonly quantity = signal(1);
  protected readonly total = computed(() => formatPrice(this.cents() * this.quantity()));
  protected readonly formatPrice = formatPrice;
  protected readonly pluralise = pluralise;

  protected onOrder() {
    this.order.emit(`${pluralise(this.quantity(), "item")} for ${this.total()}`);
  }

  protected onOneMore() {
    this.quantity.update((quantity) => quantity + 1);
  }
  protected readonly host = inject<ElementRef<HTMLElement>>(ElementRef).nativeElement;
}
```

#solid

<!-- prettier-ignore -->
```tsx [PriceTag.tsx]
import { formatPrice, pluralise } from "./format";
import { type JSX, createMemo, createSignal } from "solid-js";

export interface PriceTagEvents {
  onOrder?: (summary: string) => void;
}

export default function PriceTag(
  props: { cents: number } & PriceTagEvents & { class?: string; style?: JSX.CSSProperties },
) {
  const [quantity, setQuantity] = createSignal(1);
  const total = createMemo(() => formatPrice(props.cents * quantity()));

  function order() {
    props.onOrder?.(`${pluralise(quantity(), "item")} for ${total()}`);
  }

  return (
    <section
      class={props.class ? `price-tag ${props.class}` : "price-tag"}
      aria-label="Price"
      style={props.style}
      {...scopeAttributes(props)}
    >
      <p>Each: {formatPrice(props.cents)}</p>
      <p role="status">
        {pluralise(quantity(), "item")}: {total()}
      </p>
      <button type="button" onClick={() => setQuantity(quantity() + 1)}>
        One more
      </button>
      <button type="button" onClick={order}>
        Order
      </button>
    </section>
  );
}

/** The scope attributes of the styled parents that render this component, for its root. */
function scopeAttributes(props: object): Record<string, ""> {
  const scope: Record<string, ""> = {};
  for (const name of Object.keys(props)) if (name.startsWith("data-uf-")) scope[name] = "";
  return scope;
}
```

#qwik

<!-- prettier-ignore -->
```tsx [PriceTag.tsx]
import { formatPrice, pluralise } from "./format";
import {
  $,
  type CSSProperties,
  type ClassList,
  type QRL,
  component$,
  useComputed$,
  useSignal,
} from "@qwik.dev/core";

export interface PriceTagEvents {
  onOrder$?: QRL<(summary: string) => void>;
}

export default component$<
  { cents: number } & PriceTagEvents & { class?: ClassList; style?: CSSProperties }
>(({ cents, onOrder$, class: className, style, ...attributes }) => {
  const quantity = useSignal(1);
  const total = useComputed$(() => formatPrice(cents * quantity.value));

  const order = $(() => {
    onOrder$?.(`${pluralise(quantity.value, "item")} for ${total.value}`);
  });

  return (
    <section
      class={["price-tag", className]}
      aria-label="Price"
      {...scopeAttributes(attributes)}
      style={style}
    >
      <p>Each: {formatPrice(cents)}</p>
      <p role="status">
        {pluralise(quantity.value, "item")}: {total.value}
      </p>
      <button type="button" onClick$={() => quantity.value++}>
        One more
      </button>
      <button type="button" onClick$={order}>
        Order
      </button>
    </section>
  );
});

/** The scope attributes of the styled parents that render this component, for its root. */
function scopeAttributes(props: object): Record<string, ""> {
  const scope: Record<string, ""> = {};
  for (const key of Object.keys(props)) {
    if (key.startsWith("data-uf-")) scope[key] = "";
  }
  return scope;
}
```

#astro

<!-- prettier-ignore -->
```astro [PriceTag.astro]
---
import { formatPrice, pluralise } from "./format";

interface Props {
  cents: number;
  class?: string;
  style?: Record<string, string | number | undefined>;
}

const { cents, class: className, style } = Astro.props;

/** The scope attributes of the styled parents that render this component, for its root. */
function scopeAttributes(props: object): Record<string, ""> {
  const scope: Record<string, ""> = {};
  for (const name of Object.keys(props)) if (name.startsWith("data-uf-")) scope[name] = "";
  return scope;
}

const quantity = 1 as number;
const total = formatPrice(cents * quantity);
---

<section
  class:list={["price-tag", className]}
  aria-label="Price"
  style={style}
  {...scopeAttributes(Astro.props)}
>
  <p>Each: {formatPrice(cents)}</p>
  <p role="status">{pluralise(quantity, "item")}: {total}</p>
  <button type="button">One more</button>
  <button type="button">Order</button>
</section>
```

::

Angular's template sees only the class's members, so Angular also exposes each function it calls there as a `protected readonly` member, `formatPrice = formatPrice`. Qwik captures an imported value as a module-level import, which a `$` scope may read.

Leave the extension off the import, `./format`: each output imports its copy as written.

A module can hold types beside its values, and import another module. Each output tree holds a copy of every module the component reaches, here `units.ts` too:

<!-- prettier-ignore -->
```ts [units.ts]
// The module `format.ts` reads: each output tree holds a copy of it too (ADR-0070).
export const UNITS = { km: "kilometres", mi: "miles" } as const;

export type Unit = keyof typeof UNITS;
```

<!-- prettier-ignore -->
```ts [format.ts]
// A shared module that reads another one (ADR-0070).
import { UNITS } from "./units";
import type { Unit } from "./units";

export function formatDistance(value: number, unit: Unit): string {
  return `${value} ${UNITS[unit]}`;
}
```

## The module's own constants

A component can also read the top-level `const` declarations of its own module: a list it renders, a frozen table, a plain function, or a constant that reads another:

<!-- prettier-ignore -->
```tsx [Stepper.uf.tsx]
import { ref } from "@uxfront/unframework";

// The module's own constants (ADR-0070): a list, a frozen table, a plain function and a constant
// that reads another, all read-only, read by the component's template and its listeners.
const STEPS = [1, 5, 10] as const;
const LIMITS = Object.freeze({ min: 0, max: 20 });
const caption = (value: number): string => `${value} of ${LIMITS.max}`;
const START = LIMITS.min + 2;

export default function Stepper() {
  const value = ref(START);

  function add(step: number) {
    value.value = Math.min(LIMITS.max, value.value + step);
  }

  return (
    <section class="stepper" aria-label="Stepper">
      <p role="status">{caption(value.value)}</p>
      <ul>
        {STEPS.map((step) => (
          <li key={step}>
            <button type="button" onClick={() => add(step)}>
              Add {step}
            </button>
          </li>
        ))}
      </ul>
    </section>
  );
}
```

The module computes them as it loads, on the server too, so each is checked as setup code is: a constant may change in place only what it builds itself, like a literal, a `new` or a copy.

Module values are read-only, so every target reads one value: plain functions, literals and frozen objects. Freezing one with `Object.freeze` is fine in the component's setup and client code too, since it changes nothing anyone reads.

## What a shared module may import

A shared module may import other relative `.ts` modules, and packages. It may never import a framework, or `@uxfront/unframework`, whose `ref` and hooks exist only in `.uf.tsx` and `.uf.ts` files: every framework's output loads the copy, and one framework's import would break the six others. That's [UF1204](/docs/reference/diagnostics#UF1204), at the component's import, even when the framework is a module further away:

<!-- prettier-ignore -->
```ts [tokens.ts]
// A shared module: plain values, which every component's outputs read from their copy of it.
import { palette } from "./palette.ts";

export const tones = { info: palette.blue, danger: palette.red };
```

<!-- prettier-ignore -->
```ts [palette.ts]
// A module the shared module reaches. It imports a framework, which no other target's output can
// load: keep it to plain values, and move what needs React into a composable in a `.uf.ts` module.
import { version } from "react";

export const palette = { blue: `blue-${version}`, red: "red" };
```

The component compiles for no target. Keep the module to plain values, and move logic that needs reactivity into a [composable](/docs/components/composables), which the compiler compiles for each framework.

A few things stay out for now:

- An injection key lives in the `.uf.tsx` module that provides it, never a `.ts` module, since each framework's key is a different value ([Context](/docs/components/context)).
- A module's function passed straight as a handler, `onClick={copy}`, is [UF3029](/docs/reference/diagnostics#UF3029): a named handler is the component's own function. Call the module's function from an arrow, `onClick={() => copy()}`.
- Module state that instances share has no form, since module values are read-only. Keep the state in a component, or in a composable each component calls.

## When a shared file changes

A `.ts` module is read by every component that imports it, so an edit to it has to reach each of them, and nothing else. The compiler keeps a project graph for this: each module it compiled, what that module read, and the edges back from each file to the modules that read it. An edit then compiles again exactly the modules that depend on the file, and stops at any module whose inputs come out the same.

Let's start with four components and a props type. `B` reads the type from `a.ts`, `C` reaches it through the composable `useC`, and `D` reads nothing:

<!-- prettier-ignore -->
```ts [a.ts]
export interface CardProps {
  label: string;
}
```

<!-- prettier-ignore -->
```tsx [B.uf.tsx]
import type { CardProps } from "./a.ts";
export default function B({ label }: CardProps) {
  return <p>{label}</p>;
}
```

<!-- prettier-ignore -->
```ts [useC.uf.ts]
import { computed } from "@uxfront/unframework";
import type { CardProps } from "./a.ts";
export function useC(card: CardProps) {
  const text = computed(() => card.label);
  return { text };
}
```

<!-- prettier-ignore -->
```tsx [C.uf.tsx]
import { useC } from "./useC.uf.ts";
export default function C({ label }: { label: string }) {
  const { text } = useC({ label });
  return <p>{text.value}</p>;
}
```

<!-- prettier-ignore -->
```tsx [D.uf.tsx]
export default function D() {
  return <p>D</p>;
}
```

`createProject`, from `@unframework.dev/compiler`, builds the graph. It reads files through your `readFile`, under `root`. It also takes a type oracle over the same files, which reads the types a module imports. The options `compile()` takes, like `targets`, go to each of its compiles, but `filename` and `resolve`, which are the project's.

Its `compile(file)` compiles a module, named relative to `root`, and keeps the result with what it read. Its `update(files)` takes the files that changed and gives back what it compiled again:

<!-- prettier-ignore -->
```ts [build.ts]
import { readFile } from "node:fs/promises";

import { createProject, createSyntacticOracle } from "@unframework.dev/compiler";

const root = process.cwd();
const read = (path: string) => readFile(path, "utf8").catch(() => undefined);
const project = createProject({
  root,
  readFile: read,
  typeOracle: createSyntacticOracle({ root, readFile: read }),
  targets: ["vue"],
});
for (const file of ["B.uf.tsx", "useC.uf.ts", "C.uf.tsx", "D.uf.tsx"]) {
  await project.compile(file);
}

// After adding `hint?: string` to `CardProps` in `a.ts`:
await project.update(["a.ts"]);
// { compiled: ["B.uf.tsx", "C.uf.tsx", "useC.uf.ts"], copied: ["a.ts"] }
```

A change to the type's shape compiles `B`, `useC` and `C` again, once each, and never `D`. `C` never reads `a.ts` itself: it reads `useC`'s API, and that API reads `a.ts`, so the edit reaches `C` along the graph's edges. `copied` lists the shared modules whose copy changed, since every output tree holds `a.ts` beside its components.

An edit that leaves every shape alone, like a new `export const LABEL = "Label";` in `a.ts`, compiles no module at all: `update` gives `{ compiled: [], copied: ["a.ts"] }`. The project keeps a hash of each answer a module was given, its children's APIs and the shapes of the types it read included, and compiles a module again only where one of them changed. It still refreshes the copy of `a.ts`, so the outputs import the new text.

The Vite plugin compiles every file through one project, rooted at Vite's root, and you don't call `createProject` yourself. It tells Vite to watch every file the project says an output depends on: each child's `.uf.tsx`, each composable's `.uf.ts`, each shared `.ts` module, each stylesheet and each file a type was read from. So an edit to `a.ts` invalidates the modules of `B` and `C`, and leaves `D`'s alone. A package's files in `node_modules` get no watch, since Vite's watcher ignores them, but the plugin compares them with what the project holds before every load, so a changed package file is never missed.

The decisions behind this page are [ADR-0070](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0070-shared-modules-and-module-level-declarations.md) and, for the project graph, [ADR-0071](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0071-the-project-graph-and-incremental-invalidation.md). Shared types are on [Types and generics](/docs/components/types-and-generics).
