Registry / web-framework / componentsjs

componentsjs

JSON →
library6.4.0jsnpmunverified

Components.js is a semantic dependency injection framework for TypeScript and JavaScript projects, leveraging JSON-LD or other RDF serializations for declarative component configuration. It allows developers to define and wire software components using unique, globally identifiable URIs, promoting modular and easily reconfigurable applications. The current stable version is 6.4.0, with major releases occurring periodically, introducing breaking changes primarily related to configuration file syntax and API usage. A key differentiator is its reliance on semantic configuration, enabling dynamic component injection without hard-coding dependencies. This makes it suitable for complex applications requiring flexible component orchestration, such as the Comunica query engine.

npm install componentsjs
INSTALL
IMPORT
SIG · COMPONENTSJS
C
componentsjs
web-frameworkjavascriptv6.4.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ComponentsManager
✓ import { ComponentsManager } from 'componentsjs';
✗ const ComponentsManager = require('componentsjs');
Components.js primarily uses ESM imports since v3 and later, with `require` being a common pitfall.
compileConfig
✓ import { compileConfig } from 'componentsjs';
✗ const { compileConfig } = require('componentsjs');
Used for programmatic compilation of configurations, part of the main `componentsjs` package.
build
✓ await ComponentsManager.build({ mainModulePath: __dirname });
The static `build` method is the entry point for creating a ComponentsManager instance, requiring configuration via an options object.

This quickstart demonstrates how to set up a minimal Components.js module, define a class, create a semantic JSON-LD configuration, and then instantiate that class using the ComponentsManager. It includes a simulated `package.json` and TypeScript compilation step for a self-contained example.

import { ComponentsManager } from 'componentsjs'; import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'; import { resolve } from 'node:path'; // Create a dummy TypeScript class and compile it (in a real project, this would be part of your build process) const myClassCode = ` export class MyClass { public readonly name: string; constructor(name: string) { this.name = name; } } `; const tsOutputDirectory = resolve(process.cwd(), 'lib'); mkdirSync(tsOutputDirectory, { recursive: true }); writeFileSync(resolve(tsOutputDirectory, 'my-package.d.ts'), myClassCode); writeFileSync(resolve(tsOutputDirectory, 'my-package.js'), myClassCode.replace('export class', 'class').replace(/\: string/g, '')); // Basic JS output // 1. Define package.json (simulating a module) const packageJson = { name: 'my-package', version: '2.3.4', "lsd:module": true, main: 'lib/my-package.js', types: 'lib/my-package.d.ts' }; writeFileSync(resolve(process.cwd(), 'package.json'), JSON.stringify(packageJson, null, 2)); // 2. Create a configuration file const configContent = ` { "@context": [ "https://linkedsoftwependencies.org/bundles/npm/componentsjs/^6.0.0/components/context.jsonld", "https://linkedsoftwependencies.org/bundles/npm/my-package/^2.0.0/components/context.jsonld" ], "@id": "urn:my-package:myInstance", "@type": "MyClass", "name": "John Doe" } `; const configPath = resolve(process.cwd(), 'config.jsonld'); writeFileSync(configPath, configContent); async function runComponentsJs() { // In a real setup, `__dirname` would point to the package root, not this script's directory. // For this example, we mock `mainModulePath` to the current working directory // where we've created the dummy package.json and lib directory. const manager = await ComponentsManager.build({ mainModulePath: process.cwd(), }); await manager.configRegistry.register(configPath); const myInstance = await manager.instantiate('urn:my-package:myInstance'); console.log('Instantiated object:', myInstance); console.log('Name property:', myInstance.name); if (myInstance.name === 'John Doe') { console.log('Quickstart successful: Instance created and property accessed.'); } else { console.error('Quickstart failed: Unexpected instance property.'); } } runComponentsJs().catch(console.error);
Debug
Known issues
breakingComponents.js v6.0.0 introduced breaking changes to parameter range definition within JSON-LD configuration files. Previously, `required` and `unique` flags were used; these have been removed in favor of explicit parameter ranges. Arrays must now be explicitly defined using an RDF list (`@list` in JSON-LD). Incorrectly defined parameters will lead to configuration parsing errors.
fix
Review configuration files and update parameter definitions to use explicit RDF lists for arrays and new parameter range syntax. Consult the official v6 migration guide.
affects: >=6.0.0
breakingComponents.js v5.0.0 also introduced significant changes to parameter definition, including the removal of `required` and `unique` flags in favor of parameter ranges, similar to v6. This change also impacted how arrays are handled, requiring explicit RDF list definitions.
fix
For upgrades from v4, configurations must be updated to align with the v5 parameter range and RDF list changes. Consult the official v5 migration guide.
affects: >=5.0.0 <6.0.0
gotchaConfiguration context URLs are version-specific and should always refer to the major version range of a package (e.g., `^6.0.0`). Using an exact version or an incorrect range in `@context` URLs within your JSON-LD configuration can lead to modules and components not being found.
fix
Ensure that all `@context` URLs in `config.jsonld` (and other configuration files) use the correct major version range for `componentsjs` and any custom modules. For example, `https://linkedsoftwependencies.org/bundles/npm/componentsjs/^6.0.0/components/context.jsonld`.
affects: >=2.0.0
gotchaFor Components.js to automatically discover and use your components, your `package.json` must include the `"lsd:module": true` entry. Additionally, the `componentsjs-generator` tool (typically run via a build script) is required to generate the necessary component metadata files from your TypeScript (`.d.ts`) or JavaScript source. Skipping these steps will prevent Components.js from finding your defined components.
fix
Add `"lsd:module": true` to your `package.json` and ensure `componentsjs-generator` is installed as a dev dependency and run as part of your build process, usually via an `npm run build:components` script. Verify the output directory for TypeScript (`.d.ts`) files aligns with the generator's expected input (default `lib/`) or use the `-s` flag.
affects: >=2.0.0
Errors
Common errors & fixes
ReferenceError: MyClass is not defined (or similar for other component names)
The `componentsjs-generator` tool has not been run, or its output path is misconfigured, preventing Components.js from discovering the component metadata.
fix
Ensure `npm run build:components` (or equivalent) has been executed after compiling TypeScript/JavaScript. Verify that the generator is targeting the correct source files and outputting metadata to the expected location.
Error: Could not resolve module for component 'urn:my-package:myInstance'
Components.js cannot find the module definition. This often happens if `"lsd:module": true` is missing from the `package.json` of the component's package, or if `mainModulePath` in `ComponentsManager.build()` is incorrect.
fix
Add `"lsd:module": true` to the `package.json` of the module containing the component. Double-check that `mainModulePath` passed to `ComponentsManager.build()` correctly points to the root of the npm package.
SyntaxError: Cannot use import statement outside a module
Attempting to use ESM `import` syntax in a Node.js environment configured for CommonJS, or in an older Node.js version without proper ESM setup.
fix
Ensure your project's `package.json` includes `"type": "module"` if you intend to use ESM globally, or rename files using `import` to `.mjs`. For older Node.js, stick to CommonJS `require()` or transpile your code.
Error: Parameter 'myParameter' has no associated range
This error typically indicates that a parameter in your component's configuration (JSON-LD) is not defined correctly according to the current Components.js version's parameter range specification, or an array is not explicitly wrapped in an RDF list (`@list`).
fix
Refer to the `CHANGELOG` for your Components.js major version (v5 or v6) and update your component configuration to align with the new parameter range and RDF list requirements. Ensure all array values are explicitly defined with `@list`.
Upgrade
Version history
6.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
componentsjs — npm install componentsjs · libregistry