# @metaobjectsdev/codegen-ts-tanstack

> TanStack codegen for metaobjects — TanStack Query hooks for every entity, plus TanStack Table column definitions and grid-state hooks for entities declaring a layout.dataGrid.

Latest version **1.0.9** (published 2026-09-26) · Apache-2.0 license · 2.6K weekly downloads

## Install

```sh
npm install @metaobjectsdev/codegen-ts-tanstack
pnpm add @metaobjectsdev/codegen-ts-tanstack
yarn add @metaobjectsdev/codegen-ts-tanstack
bun add @metaobjectsdev/codegen-ts-tanstack
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; growing popularity.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2026-09-26 |
| First published | 2026-05-23 |
| Weekly downloads | 2.6K |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 206.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Doug Mealing <doug@dougmealing.com> |
| Maintainers | dougmealing |
| Keywords | metaobjects, codegen, tanstack, react-query, react-table |

## Links

- npm: https://www.npmjs.com/package/@metaobjectsdev/codegen-ts-tanstack
- Repository: https://github.com/metaobjectsdev/metaobjects
- Homepage: https://metaobjects.dev
- Issues: https://github.com/metaobjectsdev/metaobjects/issues
- npm.io page: https://npm.io/package/@metaobjectsdev/codegen-ts-tanstack

## Dependencies (3)

- [ts-poet](https://npm.io/package/ts-poet.md) ^6.10.0
- [@metaobjectsdev/metadata](https://npm.io/package/@metaobjectsdev/metadata.md) 1.0.9
- [@metaobjectsdev/codegen-ts](https://npm.io/package/@metaobjectsdev/codegen-ts.md) 1.0.9

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 1.0.9 (latest) — 2026-09-26
- 1.0.9-rc.6 (next) — 2026-09-26
- 1.0.9-rc.5 — 2026-09-26
- 1.0.9-rc.4 — 2026-09-26
- 1.0.9-rc.3 — 2026-09-26
- 1.0.9-rc.2 — 2026-09-26
- 1.0.9-rc.1 — 2026-09-26
- 1.0.8 — 2026-09-26
- 1.0.8-rc.1 — 2026-09-26
- 1.0.7 — 2026-09-24
- 1.0.7-rc.1 — 2026-09-24
- 1.0.5 — 2026-09-23
- 1.0.5-rc.11 — 2026-09-23
- 1.0.5-rc.10 — 2026-09-22
- 1.0.5-rc.9 — 2026-09-22
- … 175 more at https://npm.io/package/@metaobjectsdev/codegen-ts-tanstack/versions

## README

# @metaobjectsdev/codegen-ts-tanstack

TanStack codegen for MetaObjects. Provides `tanstackQuery()` (per-entity `<Entity>.hooks.ts` — 5 React Query hooks, plus a `use<Source><Relation>(sourceId, opts?)` collection hook per many-to-many relationship), `tanstackGrid()` (`<Entity>.columns.tsx` for `@tanstack/react-table`), and `tanstackGridHook()` (`<Entity>.grid.ts` — the controlled grid state + query).

### Grids are opt-in per entity

`tanstackQuery()` emits hooks for **every** entity. `tanstackGrid()` and `tanstackGridHook()` emit **only for an entity that declares a `layout.dataGrid` child** — declaring one is how you say "this entity is displayed in a grid". If you wire the grid generators and get no `.columns.tsx`/`.grid.ts`, that is the reason, and `meta gen` says so in its warnings. Opt an entity in with:

```jsonc
{ "layout.dataGrid": { "name": "default", "@columns": ["name", "email"] } }
```

`@columns` is an ordered list; omit it to get every field. Each `layout.dataGrid` yields a `<entity><Grid>Columns` + `<entity><Grid>Grid` pair from `tanstackGrid()` and a `use<Entity><Grid>Grid()` from `tanstackGridHook()`.

### M:N collection hooks (FR-018)

For each many-to-many relationship a source entity declares (`@cardinality: "many"` + `@through`), `tanstackQuery()` emits a `use<Source><Relation>(sourceId, opts?)` hook. It is a `useQuery` that fetches the REST sub-resource `GET /<source-plural>/{sourceId}/<relationName>` (the exact URL the generated route serves) and returns the typed target collection (`<Target>[]`). The query is enabled only when `sourceId` is present, so it is safe to call before the parent row loads. A symmetric self-join still produces a single collection hook (the server unions both junction columns on read).

## Install

```bash
pnpm add -D @metaobjectsdev/codegen-ts-tanstack
```

## Usage

In your `metaobjects.config.ts`:

```ts
import { defineConfig } from "@metaobjectsdev/cli";
import { tanstackQuery, tanstackGrid, tanstackGridHook } from "@metaobjectsdev/codegen-ts-tanstack";

export default defineConfig({
  generators: [tanstackQuery(), tanstackGrid(), tanstackGridHook()],
});
```

Then render. `<EntityGrid>` is fully controlled — beyond the columns it needs
`rowCount`, a `state` object and three `onChange` callbacks — so pair it with the
generated grid hook, which returns exactly that prop shape:

```tsx
import { EntityGrid } from "@metaobjectsdev/tanstack";
import { authorDefaultColumns, authorDefaultGrid } from "./generated/Author.columns";
import { useAuthorDefaultGrid } from "./generated/Author.grid";

export function AuthorList() {
  const grid = useAuthorDefaultGrid();   // owns sorting/pagination/filters + the query
  return <EntityGrid {...grid} columns={authorDefaultColumns} grid={authorDefaultGrid} />;
}
```

`tanstackQuery`/`tanstackGrid`/`tanstackGridHook` each accept `{ target }` to route
their output (hooks/columns/grids) to a named target such as the browser app — see
`@metaobjectsdev/cli` README, "Multiple output targets". The generated files import
the entity module from wherever `entityFile()` is routed (relative when same target,
the entity-module target's `importBase` when not); the grid-hook imports its sibling
`<Entity>.columns` from within its own target.

### The generator is yours

Each of `tanstackQuery()`, `tanstackGrid()` and `tanstackGridHook()` has a reference template:
`meta eject hooks` / `grid` / `grid-hook` copies one into `codegen/generators/` for you to own. Each
renderer (`renderHooksFile`, `renderColumnsFile`, `renderGridHookFile`) is exported, so retargeting
is usually a wrapper, not a rewrite — compose it and change the one step your framework needs.
Inside the ejected file's existing `if (!ctx.renderContext) throw …` guard, change only the
`content:` line, e.g. `content: '"use client";\n' + renderHooksFile(entity, ctx.renderContext)`.

## Pairs with

- Runtime: [`@metaobjectsdev/tanstack`](../../../../client/web/packages/tanstack) — generated hooks and columns import from here.

## Links

- [Spec](https://github.com/metaobjectsdev/metaobjects/tree/main/spec)

## License

Apache 2.0 — see [LICENSE](../../../../LICENSE) at the repo root.

---
_Source: https://npm.io/package/@metaobjectsdev/codegen-ts-tanstack · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._