DEV Community: Hamza Hamidi

Add Gherkin linting to a Node.js project

Hamza Hamidi — Thu, 08 Oct 2026 09:54:39 +0000

Gherkin feature files can parse correctly and still contain duplicate tags, repeated names or unused Scenario Outline variables. Gherkin Refine checks those issues in a Node.js project, with optional rules for whitespace cleanup. It statically checks .feature files. It does not execute scenarios or validate Cucumber step definitions.

Install and run it locally

The package requires Node.js 22.18 or later. Install it as a development dependency, then point it at your feature files:

npm install --save-dev gherkin-refine
npx gherkin-refine features/

The recommended rules run without a configuration file. They check duplicate tags, duplicate Feature and Scenario names, and unused or undeclared Scenario Outline variables. Style rules stay off until you choose to enable them.

Run it on pull requests

Add a workflow that installs the locked dependencies and lints the same feature directory used locally. The Getting started guide includes a complete GitHub Actions workflow:

name: Gherkin

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22.18.0
          cache: npm
      - run: npm ci
      - run: npx gherkin-refine features/

A lint error returns exit status 1, so the job fails. If merges should wait for the result, mark the job as a required check in branch protection.

Bring over an existing gherkin-lint setup

If the repository already uses gherkin-lint, replace the dependency:

npm uninstall gherkin-lint
npm install --save-dev gherkin-refine

Gherkin Refine installs a gherkin-lint command and reads the existing .gherkin-lintrc and .gherkin-lintignore, so scripts and CI keep working. It supports every gherkin-lint 4.2.4 rule. A few findings differ where gherkin-lint bugs were fixed, and the migration guide lists them.

To move to a native configuration instead, preview the conversion before writing it:

npx gherkin-refine migrate .gherkin-lintrc --dry-run

The migration command prints the generated configuration and reports rules it cannot map or behavior that changes. Review that output before running the command without --dry-run to write gherkin-refine.config.json. Add --strict to fail instead of writing a configuration that drops a rule.

Preview safe whitespace fixes

Whitespace rules are opt in. Add the ones that match your team's style to gherkin-refine.config.json:

{
  "extends": ["recommended"],
  "rules": {
    "no-extra-blank-lines": "error",
    "no-trailing-whitespace": "error"
  }
}

Use a dry run to see which safe fixes are available without writing the feature file:

npx gherkin-refine features/checkout.feature --fix-dry-run

The dry run reports findings and which ones have safe fixes, but does not show an edited diff. Apply fixes in your working tree and inspect the result:

npx gherkin-refine features/checkout.feature --fix
git diff -- features/checkout.feature
npx gherkin-refine features/checkout.feature

The clip shows a dry run reporting trailing whitespace and repeated blank lines, applies those whitespace fixes, displays the cleaned feature file and checks it again. Findings without a safe automatic fix remain for you to review. Formatting rules such as indentation and use-and also have safe fixes.

For every built-in rule, see the rules reference. The configuration guide, plugin guide and API example cover the next steps. Install the package from npm.

Six Old Processes Led Me to Build AgentDust

Hamza Hamidi — Mon, 05 Oct 2026 14:34:42 +0000

When my Mac started running hot, I looked at processes left around my AI coding sessions. I found six processes, each 7 to 9 days old: two development servers, a mock server, a browser driver, its MCP server, and a stale Node script. Three held ports. All six showed 0% CPU when I checked, so they were not the cause of the heat.

I had found them by checking the process list and launchctl by hand. I still had no safe rule for deciding what to stop.

There are related process leak reports for Claude Code and Codex. They describe the same class of lifecycle problem. They do not show that my six processes were all caused by those bugs.

A parent PID does not show whether work is abandoned

Killing every process whose parent PID is 1 sounds like a shortcut. In one test, a background Node job had parent PID 1 after 0.3 seconds even though the agent that launched it was still running. Parent PID describes a process relationship at that moment. It does not tell me whether the work is still needed.

Names and ports leave the same question unanswered. A process named node could be a test server, a mock, or part of an application I am using. A process holding a port is not necessarily active, abandoned, or safe to stop.

Track ownership while the session runs

I built AgentDust to associate a process with the Claude Code session whose marker it inherited. Hooks record session and shell events. At session start, a hook writes a random marker to Claude Code's environment file so child processes inherit it, and stores a keyed form in the local journal. During a survey, AgentDust hashes an inherited marker and compares it with the recorded key.

AgentDust records the agent identity so it can check whether the session's agent is still alive. Processes can be owned by a live session, owned by an ended session, suspect, managed, or unknown. Only processes owned by ended sessions and suspects can enter a cleanup plan. The doctor command only reads and reports.

Approval and revalidation

I approve a cleanup by typing a generated four-character code. The approval form does not accept a code supplied through the model's tool call. Before signaling, AgentDust takes a fresh process inventory, classifies each process again, and compares its boot session, PID, start time, user, and executable path with the identity in the plan. If a process no longer qualifies or its identity changed, AgentDust refuses to signal it. Otherwise it sends one SIGTERM to that PID.

A narrow PID reuse window remains between the last identity check and the signal call, because the operating system signal call takes a numeric PID. Revalidation reduces that risk but cannot remove it.

What I measured

The hook's measured median latency is 2.5 ms per event on a macos-15 runner. One KERN_PROCARGS2 fuzz run processed 27,196,230 inputs in 61 seconds without a crash. Two clean builds produced byte-identical binaries. The M0 report records these results.

AgentDust 0.1.0 supports Claude Code on macOS with Apple silicon. Install it with Homebrew, then connect it to Claude Code:

brew install hamzahamidi/agentdust/agentdust
agentdust setup

The cleanup skill is optional. To add it, run:

claude plugin marketplace add hamzahamidi/agentdust
claude plugin install agentdust@agentdust --scope user

Start a new Claude Code session and run /agentdust:cleanup. The repository has the implementation and setup details. The 0.1.0 release has the release artifacts.

Publishing a Chrome extension from GitHub Actions without a stored secret

Hamza Hamidi — Sat, 26 Sep 2026 02:56:31 +0000

Most of the publishing actions I looked at require a long-lived OAuth refresh token in repository secrets, and that credential can publish every extension of the publisher. Publish to Chrome Web Store, a GitHub Action at v1.2.0 since 26 September 2026, gets a 30-minute access token for each release through GitHub OIDC and Workload Identity Federation instead. It uses only the Chrome Web Store API v2, checks the store state before writing, and has no runtime dependencies.

Google's v1.1 reference says the old API is deprecated and only supported until 15 October 2026.

The credential problem

The chromewebstore OAuth scope covers every item of a publisher, not one extension, and once the store approves an upload, Chrome's auto-update delivers it to every user. Google Cloud can trust GitHub's OIDC tokens through Workload Identity Federation, and the Chrome Web Store accepts a service account linked to the publisher.

The release job exchanges its OIDC token for an access token that lasts 30 minutes:

tag push, approved in the chrome-web-store environment
    ↓  GitHub OIDC token (repository, ref and environment)
Google Workload Identity provider
    ↓  checks owner ID, repository ID, tag ref and environment
service account linked to the publisher
    ↓  access token, chromewebstore scope, 30 minutes
publish-to-chrome-web-store

publish:
  runs-on: ubuntu-latest
  environment: chrome-web-store
  permissions:
    id-token: write
  concurrency:
    group: chrome-web-store
    cancel-in-progress: false
  steps:
    - id: auth
      uses: google-github-actions/auth@v3
      with:
        workload_identity_provider: ${{ vars.CWS_WIF_PROVIDER }}
        service_account: ${{ vars.CWS_SERVICE_ACCOUNT }}
        token_format: access_token
        access_token_scopes: https://www.googleapis.com/auth/chromewebstore
        access_token_lifetime: 1800s
        create_credentials_file: false
        export_environment_variables: false
    - uses: hamzahamidi/publish-to-chrome-web-store@v1
      with:
        access-token: ${{ steps.auth.outputs.access_token }}
        publisher-id: your-publisher-id
        item-id: your-32-letter-extension-id
        zip: extension.zip

Build the ZIP in a separate job without id-token: write, so build dependencies never run next to the token.

The threat model:

Protected: the authority to update the publisher's items.
Removed: the long-lived store credential in GitHub secrets.
Still trusted: your release workflow, this action, GitHub, Google Cloud and the service account.
Still broad: the service account can act on every item of the publisher, not one extension.

Most of this protection comes from the workflow, not the action. The provider decides which repository, ref and environment get a token, and the environment decides who approves the job. On a private repository, GitHub offers required reviewers only with GitHub Enterprise (GitHub's reference); without one, limit who can push release tags, as the README describes. The action also accepts an access token minted any other way, or a client ID, client secret and refresh token that it exchanges itself. It cannot tell how a credential was issued. The README has the setup in eight steps. My Google Cloud project for it has no billing account.

Why not call the API yourself

Uploading a ZIP and calling publish takes two requests. Doing it safely on every tag takes more, because the v2 API leaves several things to the caller.

publish takes no version. It submits whatever package was uploaded last, and fetchStatus does not say which package sits in the draft. If two runs upload to the same item, one can submit the other's package. The action reads the status again after submitting and fails if a different version went to review, but only one writer per item prevents it. The README makes that a requirement, and the concurrency group in the job above keeps two releases from uploading at once.

The store refuses many uploads, and says so late. A version in review blocks new packages, and so does an approved version waiting to be published. An upload whose version is not higher than the published one is rejected. The action reads the status first and stops before uploading, with a message that names the blocking version. A version that is already published or in review is skipped, so re-running a release is safe.

Uploads can finish later. The upload call may answer that processing is still in progress. The action polls the status every 10 seconds, up to 30 times, and fails without submitting if processing takes longer. It waits for an earlier run's upload instead of racing it. When the upload completes at once, it refuses to submit if the store read a different version from the package than the one sent.

dry-run: true reads the ZIP and the store status, reports what the run would do, and stops before uploading.

Optional controls

Partial rollout. deploy-percentage submits a version to a share of users, and a later run raises it. Google allows this only for items with over 10,000 seven-day active users, and the percentage can only go up. Raising without a package needs rollout-only: true. An empty zip, such as a mistyped step output, then fails the run instead of turning a release into a rollout change.

Signed uploads. Once an item is opted in to Verified CRX Uploads, the store accepts only a CRX signed with the developer's RSA key, so a leaked store token alone cannot upload a package the developer did not sign. A companion action, hamzahamidi/publish-to-chrome-web-store/sign@v1, signs the ZIP and makes no network request. The recommended workflow runs it in a separate job whose environment holds the key and never receives the store token. Keep the key in a secret of an environment limited to release tags: GitHub states that any user with write access to a repository can read all of its repository secrets. For the same ZIP and key, the output is byte-identical to Chrome's --pack-extension, which CI checks on every change.

Why trust it with the token

The source runs as is. About 900 lines of TypeScript importing only Node.js built-ins, with no bundle and no dist/. Node 24 strips the types when it loads the files.
Two hosts. Credentials go only to chromewebstore.googleapis.com, and to oauth2.googleapis.com for the refresh token route. Redirects are refused, and the README lists every request.
Clean logs. Credentials are masked before the first log line, and store responses are escaped so they cannot start a workflow command.
Checked releases. CI runs the tests on Linux, Windows and macOS, and separate jobs run the action from its action.yml against a mock store. Releases are immutable, and v1 moves to the newest release through a workflow.

Limits

What the action does not do:

It does not publish a staged version or cancel a pending review. Do both in the dashboard.
It detects a competing upload only after the fact. Keep one writer per item.
It refuses ZIP64 archives.

What Google imposes on any publishing tool:

A Google Cloud project, since Google only issues store tokens to an OAuth client or a service account.
One service account per publisher, able to manage every item of that publisher.
No API call to create an item or change its visibility. After a visibility change, publish once by hand.
Partial rollout only above 10,000 seven-day active users, and only upward.
Replacing a lost signing key through support, which can take up to a week.

Use it

The Marketplace listing and the README have the setup. Start with dry-run: true. Yoke 0.1.7 was the first release submitted through it, on 26 September 2026.

AJSF on Angular 22, and the way up from 0.8.0

Hamza Hamidi — Thu, 24 Sep 2026 21:44:53 +0000

AJSF turns a JSON Schema into an Angular form. @ajsf/core renders plain HTML, and five framework packages render it with a UI library: @ajsf/material, @ajsf/primeng, @ajsf/bootstrap3, @ajsf/bootstrap4 and @ajsf/bootstrap5.

In the week of 15 to 21 September 2026, @ajsf/core had 2,932 npm downloads, over five days of data, since npm reports none for 15 and 17 September. As npm's versions tab showed them on 24 September, 2,289 of those were version 0.8.0, from August 2022, and 216 in total were 14.0.0 or later. So this note is mostly for people still on 0.8.0: which version to move to, what changes on the way, and what a new Angular 22 app needs.

Why so many installs are still on `0.8.0`

No AJSF release shipped between 0.8.0, published on 27 August 2022, and 14.0.0, published on 15 August 2026.

@ajsf/core@0.8.0 declares @angular/core >=14.0.0, an open range, so npm installs it next to any later Angular without a warning. @ajsf/material@0.8.0 also peers on @angular/flex-layout, whose matching releases require Angular 14, so on Angular 15 or later npm stops with ERESOLVE unless it runs with --legacy-peer-deps. Neither means the combination was ever built or tested.

From 14.0.0, the Angular peer ranges are bounded, so npm reports a resolution error instead of installing a combination nobody built. AJSF then followed Angular one major at a time, up to 22.0.0 on 12 September 2026. The current release is 22.3.1, published on 24 September 2026.

Pick the version that matches your Angular

From 14.0.0 onward, the AJSF major equals the Angular major it targets, as Angular Material does. Minor and patch numbers are not tied to Angular, so a major can have several releases, such as 22.0.0, 22.1.0, 22.2.0, 22.3.0 and 22.3.1.

The majors that exist are 14, 16, 17, 18, 19, 20, 21 and 22. There is no release for Angular 15: 16.0.0 crossed 15 on the way from 14 to 16.

A plain npm install @ajsf/material takes the newest major, which fails to resolve on an older Angular, so name the major that matches the Angular you run:

npm install @ajsf/core@17 @ajsf/material@17   # for Angular 17

@ajsf/*@17 installs 17.1.0, which has none of the fixes listed below for 18 and later. Fixes ship only in the newest release, with no backports to earlier majors, 0.8.0 or angular6-json-schema-form, so an app on an older Angular gets them by moving to Angular 22.

14.0.0 is not a rewrite: it targets the same Angular 14 as 0.8.0, and the version jump is the Angular-aligned numbering starting.

Every @ajsf release since 14.0.0 is published from the repository's release workflow with an npm provenance attestation that records the repository and workflow, and npm audit signatures verifies it.

Upgrade from `0.8.0`, one major at a time

Remove flex-layout. @ajsf/material no longer depends on @angular/flex-layout, which is deprecated and has no Angular 16 release. Unless something else uses it, run npm uninstall @angular/flex-layout --legacy-peer-deps first: while its 14.0.0 beta sits next to a newer Angular, the next install stops with ERESOLVE. The fxFlex, fxFlexOrder, fxFlexOffset, fxFlexAlign, fxLayoutAlign and fxLayoutGap options and the flex and section layout types still apply, as native CSS, for values written with a unit such as 30% or 10px.
Match your Angular. Install the @ajsf major for the Angular you run, for every @ajsf package you use, as above.
Move Angular and AJSF up one major together with one ng update that names every @ajsf package you use, as Angular's update guide describes, for example ng update @angular/core@18 @angular/cli@18 @angular/material@18 @ajsf/core@18 @ajsf/material@18. Without the @ajsf packages, ng update stops with Incompatible peer dependencies found, because @ajsf/material@17 peers on @angular/material ^17.0.0.
Check your forms against the list below, then repeat step 3 up to Angular 22.

What a form can notice between `0.8.0` and `22`

The 20.0.0, 21.0.0 and 22.0.0 releases changed no export, selector or input, while minors inside those majors changed Bootstrap markup. The changes below, from 16 to 22, can affect what a form shows, validates or submits, or what your project needs to build it. Upgrade notes for 19 to 22 are in the release notes directory; for 14 to 18, read each release's page in the GitHub releases.

16.0.0, Material: the widgets use Angular Material's MDC components (#367). A field without an appearance option renders as fill instead of standard. CSS written against .mat-form-field-* classes needs the .mat-mdc-* names.
17.1.0, messages: validator and locale messages are corrected (#374), for example the message for a decimal multipleOf step.
18.x, field validators: duplicates under uniqueItems (#379), exclusive bounds (#418) and an emptied array under minItems (#396) now mark the field, and dependencies is checked per field (#376). Decimal multipleOf steps and emoji in length limits stop showing false errors (#396). isValid and submit come from ajv, which already judged all of these cases correctly, so what changes is the message on the field.
19.0.0, format: 0.8.0 already checked format with ajv 6. From 19.0.0, ajv 8 with ajv-formats is stricter, so 2021-02-30 no longer passes format: date and a@b no longer passes format: email.
19.0.0, drafts: the draft is read from $schema, and a schema without it is read as draft 7, though draft 4 keywords are still converted, so a draft 4 schema without $schema keeps working. Draft 4 is the oldest draft supported: a schema declaring draft 3 still renders, with its property-level keywords handled as in the next bullet.
19.0.0, property-level required: a property-level required: true, optional or requires is dropped with a console warning naming the properties, so that field is no longer required. Move each required: true name into the parent object's required array, list there every property without optional: true, and turn requires into a dependencies entry. This is the change most likely to need a schema edit.
19.0.0, references and selects: $ref against a schema's own id resolves. A select over a numeric enum submits numbers instead of strings, and clearing an optional select with its None option no longer makes the form invalid.
19.0.0, counts and buttons: minProperties and maxProperties count only entered values: undefined, null and the empty string do not count, false and 0 do. A layout-declared submit button honours disableInvalidSubmit, and fixed tuple positions show no remove button.
20.0.0 and 22.0.0, toolchain: moving to 20 needs Node ^20.19.0 || ^22.12.0 || >=24.0.0 (20 notes). At 22, TypeScript must be >=6.0 <6.1 and Node ^22.22.3 || ^24.15.0 || >=26.0.0 (22 notes). TypeScript 6 turns strict on when tsconfig.json does not set it, so set "strict": false or fix the new errors, and it deprecates baseUrl with TS5101: without baseUrl, each paths target needs a leading ./.
20.1.0, Bootstrap 4 classes: @ajsf/bootstrap4 emits Bootstrap 4 class names instead of Bootstrap 3 ones, for example is-invalid instead of has-error. The package README tables every replacement.
22.1.0, Bootstrap 4 and 5 checkboxes and radios: the input and its label render as siblings instead of the label wrapping the input, except Bootstrap 4 toggle buttons, which stay nested. CSS selecting label > input no longer matches.

  <div class="form-check">
    <input class="form-check-input" id="control1" type="checkbox">
    <label class="form-check-label" for="control1">Accept</label>
  </div>

The snippet matches Bootstrap 4 and the Bootstrap 5 radios and checkbox lists. For a single Bootstrap 5 checkbox, the input and label share a div nested inside .form-check, so a descendant selector matches every case.

22.2.0, Bootstrap arrays: an array title renders once, on the <legend>, in all three Bootstrap packages. In Bootstrap 4 and 5, every field sits in a wrapper row that carries is-invalid and, for an array item, holds the remove button beside the field, so a selector such as .input-group.is-invalid no longer matches.
22.3.0, Bootstrap messages: in all three Bootstrap packages, a field's validation message appears under it once the field is touched or changed (#524). Bootstrap 5 puts is-invalid on the wrapper around the field, not on the input, and the red border on a touched invalid input comes from AJSF's own .ng-invalid.ng-touched rule.
New packages: @ajsf/bootstrap5 is released from 18.0.0 and @ajsf/primeng from 19.2.0. Neither existed in 0.8.0.

Before each release, 74 recorded schemas are rendered in every framework, 444 cases in all, and their control count and validity are compared with a recorded baseline. That baseline holds no class names, so the Bootstrap markup changes above do not show in it.

A new Angular 22 app

I built and ran this setup in Chrome on 24 September 2026 with Angular CLI 22.2.0, Angular Material 22.2.0 and @ajsf 22.3.1. The CLI scaffolds a standalone, zoneless app, and this Material setup needs neither zone.js nor @angular/animations.

npx @angular/cli@22 new ajsf-demo --defaults --style=css
cd ajsf-demo
npx ng add @angular/material
npm install @ajsf/material

ng add @angular/material asks whether to proceed and which palette, and its defaults give the setup below: it installs Material and the CDK, writes a theme and links the fonts. @ajsf/material brings @ajsf/core with it; an app that already lists @ajsf/core names it in the install too, so both stay on the same version.

Nothing goes in app.config.ts: MaterialDesignFrameworkModule goes in the component's imports and provides what the form needs. An app that still bootstraps an NgModule adds it to that module's imports instead.

In src/app/app.ts:

import { Component, signal } from '@angular/core';
import { JsonPipe } from '@angular/common';
import { MaterialDesignFrameworkModule } from '@ajsf/material';

@Component({
  selector: 'app-root',
  imports: [MaterialDesignFrameworkModule, JsonPipe],
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {
  protected readonly schema = {
    type: 'object',
    properties: {
      name: { type: 'string', title: 'Name', minLength: 1 },
      age: { type: 'integer', title: 'Age', minimum: 18 },
      plan: { type: 'string', title: 'Plan', enum: ['free', 'pro', 'team'] },
    },
    required: ['name'],
  };

  protected readonly submitted = signal<unknown>(null);

  protected onSubmit(data: unknown): void {
    this.submitted.set(data);
  }
}

In src/app/app.html:

<json-schema-form
  [schema]="schema"
  framework="material-design"
  (onSubmit)="onSubmit($event)">
</json-schema-form>

<pre>{{ submitted() | json }}</pre>

The browser showed Name, Age and Plan as Material form fields and a select, with the required asterisk on Name and Submit disabled. Touching Name and leaving it empty showed This field is required., and typing 16 in Age and leaving the field showed Must be 18 or more.

With valid values, Submit called the handler with:

{ "name": "Ada Lovelace", "age": 36, "plan": "pro" }

Age arrived as a number.

The production bundle was 1.40 MB, and a new project fails the build above 1 MB. Raise the initial entry under budgets in the production configuration of angular.json:

{
  "type": "initial",
  "maximumWarning": "2MB",
  "maximumError": "2.5MB"
}

The build also warns that ajv and ajv-formats are CommonJS. Listing them in allowedCommonJsDependencies in the build options silences the warning:

"allowedCommonJsDependencies": ["ajv", "ajv-formats"]

The example leaves loadExternalAssets off. If your templates set it, bind it as [loadExternalAssets]="true": a project created by ng new rejects the plain attribute loadExternalAssets="true" with TS2322. It loads CDN assets for trying the library out (for Material only the Roboto and Material Icons fonts, not a theme), so a production app loads its own and leaves the input off.

Switching framework

Four things change for Bootstrap 5: the package, the module import, the framework value and the stylesheet.

npm install @ajsf/bootstrap5 bootstrap@5

-import { MaterialDesignFrameworkModule } from '@ajsf/material';
+import { Bootstrap5FrameworkModule } from '@ajsf/bootstrap5';

-  imports: [MaterialDesignFrameworkModule, JsonPipe],
+  imports: [Bootstrap5FrameworkModule, JsonPipe],

-  framework="material-design"
+  framework="bootstrap-5"

In angular.json, replace src/material-theme.scss in the styles array with the Bootstrap stylesheet:

"styles": [
  "node_modules/bootstrap/dist/css/bootstrap.min.css",
  "src/styles.css"
]

The Bootstrap 5 bundle is 827 kB, which passes the default 1 MB error budget, though the build still warns above 500 kB. Bootstrap 4 works the same way with @ajsf/bootstrap4, bootstrap@4, Bootstrap4FrameworkModule and framework="bootstrap-4".

PrimeNG works the same way with PrimengFrameworkModule and framework="primeng", plus providePrimeNG with a theme preset in app.config.ts, as the @ajsf/primeng README shows. Its bundle is 1.55 MB, so it needs the raised budget too.

An app can use several framework packages at once: import each framework module in the component that renders its form, and give that form the matching framework value. The playground also switches between them at runtime. The framework values are material-design, primeng, bootstrap-3, bootstrap-4, bootstrap-5 and no-framework, the default, which JsonSchemaFormModule from @ajsf/core renders as plain HTML.

Which JSON Schema it understands

AJSF understands draft 4, draft 6 and draft 7. Draft 4 keywords are converted whether or not a schema declares $schema, so a draft 4 schema without it keeps working.

A declared draft 4, 6 or 7 $schema is recognised over http or https and with or without the trailing #, from 22.3.1. 2019-09 and 2020-12 are not supported: a schema declaring either fails to compile, and the form does not render.

if, then and else validate, so a conditionally required field keeps Submit disabled. The layout is built once, though, so that field shows no required marker and no message, even after it is touched. readOnly and writeOnly are accepted and have no effect.

The playground has 71 example schemas, each viewable with Material, PrimeNG, Bootstrap 3, 4 or 5, or plain HTML.

What isn't there yet

Support for 2019-09 and 2020-12, and a layout that follows if, then and else, both described above.
A single validator. JSON Schema is validated twice today, by ajv for isValid and validationErrors and by hand-written per-field validators, and the two can disagree.
A daisyUI package is next on the roadmap. ng-zorro and Ionic wait until users ask for them in an issue.

History and links

AJSF has continued dschnelldavis/angular2-json-schema-form in its own repository since July 2018. It first shipped as the single package angular6-json-schema-form, whose last release is 8.0.0, and later moved to the @ajsf scope. What it led to is in my note on Texaryn.

Playground
API reference
llms.txt for AI assistants
README
Release notes
Issues. Security reports go through GitHub private vulnerability reporting, not a public issue.

Originally published at hamidihamza.com.

Texaryn: one JSON Schema, rendered in React, Vue or a web component

Hamza Hamidi — Thu, 24 Sep 2026 10:06:45 +0000

Texaryn is a headless runtime for JSON Schema forms. A schema adapter reads Draft 7, 2019-09 or 2020-12, a framework-neutral core owns state, validation and submission, and a React, Vue or Web Components binding renders the result.

If you've shipped react-jsonschema-form, here's what's different: array row identity lives in the runtime and follows the row's data or an itemKey you name, each field chooses whether it validates on blur, change or submit, and the same runtime renders under React, Vue or a web component. It's pre-1.0.

Why I built it

I've maintained AJSF, the Angular JSON Schema form library, since 2018. It continues dschnelldavis/angular2-json-schema-form in its own repository: the first commit, in July 2018, brought that code to Angular 6. Its major version follows the Angular major it targets, and 22.2.1 is on Angular 22.

It has 359 stars and 177 forks, and @ajsf/core had 17,630 npm downloads from 23 August to 21 September 2026.

AJSF already keeps the schema logic apart from the design system (Material, Bootstrap, PrimeNG), but all of it runs inside Angular. Texaryn grew out of that, and out of exploring what AI needs to build interfaces: describe the interface as structured data, let a runtime own state and validation, and keep rendering in a thin layer per framework.

In RJSF, Form processes the schema, manages state and renders, all in React. I wanted three separate owners: an adapter that understands JSON Schema, a runtime that owns form state, and a binding that renders a framework-neutral description of the form.

The first user I had in mind builds form-heavy React apps from JSON Schema: configuration screens, multi-step onboarding, admin panels, data entry tools. They want per-field dirty and touched state, validation timing per field, and custom components without forking a theme, in React today without being locked into React. Vue was the second binding on purpose: setup runs once and reactivity is tracked per ref, where React re-runs a component on every render, so it shows whether the binding contract quietly assumed React's model.

How it works

JSON Schema
    ↓  adapter (@texaryn/schema-json)
SchemaProjection
    ↓  compiler (@texaryn/core)
UIDocument
    ↓  runtime (@texaryn/core)
FormRuntime state
    ↓  binding (@texaryn/react, @texaryn/vue, @texaryn/web-components)
Widgets (a default set per binding; Bootstrap 5 and Material UI for React)

createJsonSchemaAdapter returns an object that implements SchemaEvaluationPort, the interface the runtime calls to project and validate data. A projection is the fields, constraints and active branches for the current data, so it's recomputed as the user edits.

The compiler turns the projection into a UIDocument: a versioned tree of typed nodes that says what the form contains, not how React, Vue or the DOM draws it. A binding receives that document rather than the schema, so conditionals, composition and dependencies are evaluated in one place, the adapter, and no binding reimplements them.

FormRuntime owns values, validation, dirty and touched state, visibility, disabled state, submission and array identity. Bindings subscribe to it instead of keeping their own copy. The core has no dependencies at all, and the UI definition is data: no generated JavaScript and no eval().

On the rendering side, a binding (@texaryn/react, @texaryn/vue, @texaryn/web-components) connects the runtime to a framework. A registry maps each UI node to a component, and a widget set such as @texaryn/react-bootstrap or @texaryn/react-mui is a ready-made registry for React.

The repository checks the neutrality claim: every example in its catalog runs through each binding and widget set, and the build fails when a documented feature has no example. The playground shows the same examples through React Default, React Bootstrap 5, React Material UI, Vue Default and Web Components Default.

The schema

All three examples render this schema.ts:

export const schema = {
  $schema: 'https://json-schema.org/draft/2020-12/schema',
  type: 'object',
  title: 'Profile',
  properties: {
    name: { type: 'string', title: 'Name', minLength: 1 },
    age: { type: 'integer', title: 'Age', minimum: 18 },
  },
  required: ['name'],
}

required only checks that the key exists, and '' counts as a value, so minLength: 1 is what rejects an empty name.

In React

pnpm add @texaryn/core @texaryn/schema-json @texaryn/react react react-dom

@texaryn/react needs React 18 or newer. The packages are ES modules only, and the examples await the adapter at module top level, which needs a build target that supports it, such as es2022.

import { createRoot } from 'react-dom/client'
import { createJsonSchemaAdapter } from '@texaryn/schema-json'
import {
  ErrorSummary,
  FormProvider,
  FormRoot,
  createDefaultRegistry,
  useForm,
} from '@texaryn/react'
import { schema } from './schema'

const adapter = await createJsonSchemaAdapter(schema)
const registry = createDefaultRegistry()

function App() {
  const form = useForm(adapter, {
    initialData: { name: '', age: 18 },
    hints: {
      '/name': { placeholder: 'Ada Lovelace', validationTrigger: 'blur' },
    },
    onSubmit: async (data) => console.log(data),
  })

  return (
    <FormProvider value={form.runtime}>
      <ErrorSummary />
      <FormRoot registry={registry} />
      <button
        type="button"
        disabled={
          form.submission.status === 'validating' ||
          form.submission.status === 'submitting'
        }
        onClick={() => form.dispatch({ type: 'Submit' })}
      >
        Submit
      </button>
    </FormProvider>
  )
}

createRoot(document.getElementById('root')!).render(<App />)

useForm creates the runtime and subscribes to its stores, and FormProvider makes it available to ErrorSummary and FormRoot. FormRoot renders fields only, with no <form> around them, so the button dispatches the Submit command itself and Enter doesn't submit. With an empty name, onSubmit isn't called, and ErrorSummary takes focus under the heading "There is a problem" and lists Name: Value `#/name` should have a minimum length of `1`, but got `0`.

That message comes from the validator, and there's no way to rewrite it yet. The default widgets set aria-invalid and link aria-describedby through getInputProps and getErrorProps, which a custom widget can call too.

Hints go in the same options as initialData, keyed by JSON Pointer. A field hint sets widget, order, placeholder, helpText or validationTrigger ('blur', 'change' debounced 300 ms by default, or 'submit'), and an array hint adds itemKey and canReorder. A field without a validationTrigger validates only on submit, so in the Vue and web component examples below an error stays until the next submit.

Submission is a state machine: idle, validating, submitting, submitted. Submit validates an immutable snapshot of the data, and an edit during validating cancels the attempt.

In Vue

pnpm add @texaryn/core @texaryn/schema-json @texaryn/vue vue

@texaryn/vue needs Vue 3.5 or newer. main.ts:

import { createApp } from 'vue'
import { createJsonSchemaAdapter } from '@texaryn/schema-json'
import App from './App.vue'
import { schema } from './schema'

const adapter = await createJsonSchemaAdapter(schema)

createApp(App, { adapter }).mount('#app')

App.vue:

<script setup lang="ts">
import type { SchemaEvaluationPort } from '@texaryn/core'
import {
  ErrorSummary,
  FormRoot,
  createDefaultRegistry,
  provideFormRuntime,
  useForm,
} from '@texaryn/vue'

const props = defineProps<{ adapter: SchemaEvaluationPort }>()

const form = useForm(props.adapter, {
  initialData: { name: '', age: 18 },
  onSubmit: async (data) => console.log(data),
})
provideFormRuntime(form.runtime)

const { submission, dispatch } = form
const registry = createDefaultRegistry()
</script>

<template>
  <ErrorSummary />
  <FormRoot :registry="registry" />
  <button
    type="button"
    :disabled="submission.status === 'validating' || submission.status === 'submitting'"
    @click="dispatch({ type: 'Submit' })"
  >
    Submit
  </button>
</template>

The adapter is created in main.ts and passed as a prop, so setup stays synchronous and needs no <Suspense>. provideFormRuntime takes the place of FormProvider, which is why ErrorSummary and FormRoot sit in this component's template: they have to be descendants of the component that provided the runtime.

@texaryn/vue ships render functions, so single-file components are your choice rather than a requirement.

As a web component

pnpm add @texaryn/core @texaryn/schema-json @texaryn/web-components

import { createJsonSchemaAdapter } from '@texaryn/schema-json'
import { createDefaultRegistry, defineTexarynForm } from '@texaryn/web-components'
import type { TexarynFormElement } from '@texaryn/web-components'
import { schema } from './schema'

defineTexarynForm()

const adapter = await createJsonSchemaAdapter(schema)

const form = document.createElement('texaryn-form') as TexarynFormElement
form.registry = createDefaultRegistry()
form.errorSummary = true
form.options = {
  initialData: { name: '', age: 18 },
  onSubmit: async (data) => console.log(data),
}
form.port = adapter
document.body.append(form)

const submit = document.createElement('button')
submit.type = 'submit'
submit.textContent = 'Submit'
form.querySelector('form')!.append(submit)

defineTexarynForm() registers the element explicitly: importing the package defines nothing. The element renders its own <form novalidate> and turns a submit event into the Submit command, so a type="submit" button inside it works. Set options before port: on an element that's already in the page, options set after port are ignored.

The element emits texaryn-data-change and texaryn-submission-change. Instead of port and options it can take a runtime you created, which it borrows and never destroys, so one runtime can render through several bindings (setting both throws). The package depends on @texaryn/core only and loads no stylesheet.

What JSON Schema it understands

The adapter reads Draft 7, 2019-09 and 2020-12. Draft 4 and Draft 6 aren't supported, and they aren't rejected either: a missing or unrecognized $schema falls back to Draft 7, and createJsonSchemaAdapter(schema, { defaultDialect }) changes that fallback.

Validation is delegated to json-schema-library. The adapter asserts format in Draft 7, which includes a schema with no $schema, and never in 2019-09 or 2020-12, with no option to change that.

The official JSON Schema Test Suite measures that validation, not which keywords get a form control. Mandatory tests passed by @texaryn/schema-json at suite revision f6fd52a, from the conformance page:

Dialect	Passed	Mandatory tests
Draft 7	917	929
2019-09	1,244	1,261
2020-12	1,278	1,301

Every mandatory failure is external schema resolution: the suite expects remote documents from http://localhost:1234, and the adapter has no resolver hook. It fails closed, so an unresolved reference is a $ref validation error rather than a skipped check. The page deliberately gives no combined percentage.

In practice, a schema that $refs another document fails validation wherever data reaches that reference, and a root that is only a remote $ref makes createFormRuntime throw Schema projection missing root node. Bundle it into one document with local $refs first, which also work at the root.

Projection has its own limits. Tuple arrays (prefixItems in 2020-12, or an array-valued items in Draft 7 and 2019-09) get no dedicated projection, patternProperties and additionalProperties generate no fields, and remote $ref, $dynamicRef and $recursiveRef are out of scope. A oneOf or anyOf branch is chosen from the current data, so there's no branch picker, and schema default values aren't written into the data unless you pass initialization: 'schema-defaults'.

Coming from RJSF

RJSF	Texaryn
`schema` prop	`createJsonSchemaAdapter(schema)`
`uiSchema`	hints keyed by JSON Pointer
`formData` / `onChange`	`initialData` option, `data` store
schema `default` values in the data	`initialization: 'schema-defaults'` (off by default)
widgets, templates, fields	renderer registry, `WidgetComponent`, `NodeRenderer`
array rendering	`useFieldArray` with stable item identity
`liveValidate`	`validationTrigger` hints
`validate`, `customValidate`	no equivalent yet: only the schema validates
`onSubmit`	`onSubmit` option plus the submission lifecycle
`showErrorList` / `ErrorList`	`ErrorSummary`
`transformErrors`, `extraErrors`	no equivalent

uiSchema: { email: { 'ui:placeholder': '...' } } becomes hints: { '/email': { placeholder: '...' } }. formContext becomes React context or props, and templates become registry entries.

Adding, removing and moving rows keeps each row's identity. When Reset replaces the data, rows are matched to their old identities by value, so an edited row gets a new identity and two identical rows can swap theirs, unless an itemKey hint names a JSON Pointer inside each row, such as '/id', to match on instead. The migration guide covers the rest.

What isn't there yet

Stability. It's pre-1.0, and @texaryn/core went from its first publish on 30 August 2026 to 0.12.1 on 23 September, so pin exact versions. These examples run with @texaryn/core 0.12.1, @texaryn/schema-json 0.6.3, @texaryn/react 0.5.2, @texaryn/vue 0.4.2 and @texaryn/web-components 0.4.1.
Validation beyond the schema. No custom or async validators and no server errors after validation. The runtime accepts a port whose validate returns a promise, but the published adapter only validates against the schema.
Widget sets for Vue and Web Components. Bootstrap 5 and Material UI exist for React only.
Web component integration. The element renders its own <form> in light DOM, so it can't sit inside another <form>. It has no Shadow DOM, formAssociated or ElementInternals.
AI generation tooling. None ships yet; it's on the roadmap. Today a generated schema and hints go through createJsonSchemaAdapter and hints like hand-written ones.

Try it

Documentation, starting with getting started and the architecture.
Playground: every catalog example through all five renderers.
Schema details: JSON Schema support and the validation test suite figures.
Coming from RJSF: the migration guide.
API reference, the packages on npm and llms.txt for coding agents.
Source and the roadmap.

If you try it and hit a missing extension point, a confusing renderer contract or a schema that doesn't project the way you expect, open an issue.

Originally published at hamidihamza.com.

DEV Community: Hamza Hamidi

Add Gherkin linting to a Node.js project

Install and run it locally

Run it on pull requests

Bring over an existing gherkin-lint setup

Preview safe whitespace fixes

Six Old Processes Led Me to Build AgentDust

A parent PID does not show whether work is abandoned

Track ownership while the session runs

Approval and revalidation

What I measured

Publishing a Chrome extension from GitHub Actions without a stored secret

The credential problem

Why not call the API yourself

Optional controls

Why trust it with the token

Limits

Use it

AJSF on Angular 22, and the way up from 0.8.0

Why so many installs are still on 0.8.0

Pick the version that matches your Angular

Upgrade from 0.8.0, one major at a time

What a form can notice between 0.8.0 and 22

A new Angular 22 app

Switching framework

Which JSON Schema it understands

What isn't there yet

History and links

Texaryn: one JSON Schema, rendered in React, Vue or a web component

Why I built it

How it works

The schema

In React

In Vue

As a web component

What JSON Schema it understands

Coming from RJSF

What isn't there yet

Try it

Why so many installs are still on `0.8.0`

Upgrade from `0.8.0`, one major at a time

What a form can notice between `0.8.0` and `22`