aasx-parser

💡 Official Scoped Package: Also available as @adarrsh_dev/aasx. Both packages share the exact same clean-room Rust WebAssembly engine.

Parse Asset Administration Shell (.aasx) packages in the browser, Node.js, edge workers, and CI. A Rust → WebAssembly engine for AAS V3 and Digital Product Passport data. Zero dependencies, zero network calls, ~186 kB gzipped.

npm i aasx-parser

• Reads .aasx (IDTA-01005 OPC packages) with XML or JSON environments, plus embedded files
• Exports AAS V3 JSON that passes aas-core3.0 verification
• Runs anywhere: Node ≥ 20, browsers, Cloudflare Workers, and a CLI
• Private by construction: no telemetry, no outbound requests, your files stay in memory

Live demo · Repository · Changelog

CLI

npx aasx-parser sample -o demo.aasx           # fictional ACME sample package
npx aasx-parser inspect demo.aasx             # shells, submodels, embedded files
npx aasx-parser to-json demo.aasx -o env.json # AAS V3 JSON

If you install the package, the binary is called aasx: npm i -g @adarrsh_dev/aasx && aasx inspect demo.aasx.

Quickstart

Node.js

import { open } from 'aasx-parser';
import { readFile, writeFile } from 'node:fs/promises';

const pkg = await open(await readFile('demo.aasx'));
try {
  for (const sm of pkg.submodels) console.log(sm.idShort, sm.semanticId?.keys?.[0]?.value);

  for (const f of pkg.files()) console.log(f.path, f.contentType);
  await writeFile('datasheet.pdf', pkg.file('/aasx/files/datasheet.pdf'));

  await writeFile('env.json', pkg.toJSON());
} finally {
  pkg.free();
}

TypeScript with using (recommended)

Parsed packages live in WebAssembly memory, which the JS garbage collector can't see. AasxPackage implements Symbol.dispose, so using frees that memory automatically when the scope ends, including on a thrown error:

import { open, type AasxPackage } from 'aasx-parser';

async function countSubmodels(bytes: Uint8Array): Promise<number> {
  using pkg: AasxPackage = await open(bytes);
  return pkg.submodels.length;
} // pkg.free() runs here

This works natively in Node 24+ and current Chromium. Elsewhere, compile with TypeScript ≥ 5.2 ("target": "ES2022", "lib": ["ESNext", "ESNext.Disposable"]). If you can't use either, call pkg.free() in a finally block. Once a package is freed, file() and fileDataUrl() throw.

Browser (Vite / vanilla)

import { init, open } from 'aasx-parser';
import wasmUrl from '@adarrsh_dev/aasx/wasm/aasx_bg.wasm?url'; // Vite: emits the .wasm as a hashed asset

await init({ wasm: wasmUrl });

document.querySelector('input[type=file]').addEventListener('change', async (e) => {
  using pkg = await open(e.target.files[0]);           // File and Blob are accepted directly
  document.querySelector('img').src = pkg.thumbnailDataUrl() ?? '';
});

Without Vite, init() with no arguments fetches aasx_bg.wasm relative to the module URL, so serve node_modules/@adarrsh_dev/aasx/wasm/ alongside your bundle. Make sure your server sends the application/wasm MIME type.

Next.js (App Router)

On the server (Route Handler):

// app/api/inspect/route.ts
import { open } from 'aasx-parser';
export const runtime = 'nodejs';

export async function POST(req: Request) {
  using pkg = await open(new Uint8Array(await req.arrayBuffer()));
  return Response.json({ shells: pkg.shells.length, submodels: pkg.submodels.map(s => s.idShort) });
}

// next.config.js — load the package from node_modules at runtime so the .wasm is read from disk
module.exports = { serverExternalPackages: ['@adarrsh_dev/aasx'] };

On the client (the file never leaves the browser):

'use client';
export function AasxDrop() {
  async function onFile(file: File) {
    const { open } = await import('@adarrsh_dev/aasx'); // keep WASM out of the initial bundle
    using pkg = await open(file);
    console.log(pkg.submodels);
  }
  return <input type="file" accept=".aasx" onChange={e => e.target.files && onFile(e.target.files[0])} />;
}

Cloudflare Workers

Wrangler imports .wasm files as a precompiled WebAssembly.Module. Pass it to init:

import wasm from '@adarrsh_dev/aasx/wasm/aasx_bg.wasm';
import { init, open } from 'aasx-parser';

export default {
  async fetch(req) {
    await init({ wasm });                               // idempotent, cheap after the first call
    using pkg = await open(new Uint8Array(await req.arrayBuffer()));
    return new Response(pkg.toJSON(), { headers: { 'content-type': 'application/json' } });
  },
};

Formal validation with aas-core3.0

toAasCore() returns a plain JSON object that you pass to the official @aas-core-works/aas-core3.0-typescript deserializer and verifier. Use it as a CI gate for supplier packages:

import { createRequire } from 'node:module';
import { readFile } from 'node:fs/promises';
import { open } from 'aasx-parser';

// aas-core3.0-typescript 1.0.x: load the CommonJS build in Node ESM (its ESM build has extensionless imports)
const aas = createRequire(import.meta.url)('@aas-core-works/aas-core3.0-typescript');

using pkg = await open(await readFile(process.argv[2]));

const parsed = aas.jsonization.environmentFromJsonable(pkg.toAasCore());
if (parsed.error !== null) {
  console.error(`schema: ${parsed.error.path} ${parsed.error.message}`);
  process.exit(1);
}

let errors = 0;
for (const err of aas.verification.verify(parsed.mustValue())) {
  console.error(`constraint: ${err.path} ${err.message}`);
  errors++;
}
process.exit(errors ? 1 : 0);

The built-in sample (getSampleAasx()) passes this check with 0 errors.

Headless view model

To render a package in your own UI (React, Vue, Svelte, a terminal), map it into a UI-agnostic view model:

import { open } from 'aasx-parser';
import { toHeadlessViewModel } from '@adarrsh_dev/aasx/headless';

using pkg = await open(bytes);
const vm = toHeadlessViewModel(pkg, { language: 'de' });

vm.nameplate?.manufacturerName;   // Digital Nameplate fields, resolved and localized
vm.technicalData?.sections;       // grouped properties with units and formatted values
vm.documentation?.documents;      // handover documents as data URLs
vm.tree;                          // a generic TreeNode[] for anything else

The same API ships standalone, without WASM, as @adarrsh_dev/aasx-headless.

API

| Export | Signature | Notes | |---|---|---| | open | (input: Uint8Array \| ArrayBuffer \| Blob) => Promise<AasxPackage> | Calls init() for you. File is a Blob. | | init | (opts?: { wasm?: WebAssembly.Module \| BufferSource \| Response \| string \| URL }) => Promise<void> | Optional. Idempotent. Use it to supply the WASM yourself. | | getSampleAasx | () => Promise<Uint8Array> | Built-in fictional ACME sample. | | AasxPackage#environment | object | Full AAS V3 environment. | | #shells / #submodels / #conceptDescriptions | AasShell[] / AasSubmodel[] / AasConceptDescription[] | | | #files() | () => { path, contentType }[] | Every part in the OPC container. | | #file(path) | (path: string) => Uint8Array | Raw bytes of an embedded file. Throws if freed. | | #fileDataUrl(path) | (path: string) => string | data:<mime>;base64,… | | #thumbnailDataUrl() | () => string \| null | Package thumbnail as a data URL. | | #toJSON() | () => string | Pretty-printed AAS V3 JSON. | | #toAasCore() | () => object | JSON object for aas.jsonization.environmentFromJsonable. | | #free() / [Symbol.dispose]() | () => void | Releases WASM memory. Safe to call twice. | | @adarrsh_dev/aasx/headless | toHeadlessViewModel(pkg, { language? }), getLocalizedText(val, lang?) | See above. | | @adarrsh_dev/aasx/wasm/aasx_bg.wasm | asset | For bundlers and Workers. |

Compatibility

| Runtime / bundler | Status | Notes | |---|---|---| | Node.js 20 / 22 / 24 | ✅ tested in CI | Native using on 24+ | | Vite 5+ (browser) | ✅ tested in CI | Use the ?url import above | | Chromium / Firefox / Safari (current) | ✅ tested in CI | ES modules + WebAssembly | | Cloudflare Workers | ✅ tested in CI | Pass the .wasm module to init | | Next.js 15+ App Router | ⚠️ example only | Server: serverExternalPackages; client: dynamic import | | Bun | ⚠️ expected to work | Uses the Node fs loader path | | Deno 2 | ⚠️ expected to work | import … from 'npm:@adarrsh_dev/aasx' |

Privacy

The package makes no network requests of its own. The only fetch happens in the browser when you call init() with no arguments, and it loads aasx_bg.wasm from the URL your bundler serves. Supply the bytes yourself to make even that local.

Provenance

Releases are built from source in GitHub Actions and published with npm provenance. Verify your install with:

npm audit signatures

License

MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE. Third-party attributions are in THIRD_PARTY_NOTICES.md. Not affiliated with IDTA or the Eclipse Foundation.