# componentsjs

> A semantic dependency injection framework

Latest version **6.4.0** (published 2026-01-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install componentsjs
pnpm add componentsjs
yarn add componentsjs
bun add componentsjs
```

Provides the command `componentsjs-compile-config`.

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 6.4.0 |
| Published | 2026-01-07 |
| First published | 2017-11-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 14 |
| Unpacked size | 312.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 42 |
| Author | Ruben Taelman |
| Maintainers | rubensworks |
| Keywords | lsd, linked software dependencies, components, dependency injection |

## Links

- npm: https://www.npmjs.com/package/componentsjs
- Repository: https://github.com/LinkedSoftwareDependencies/Components.js
- Homepage: https://github.com/LinkedSoftwareDependencies/Components.js#readme
- Issues: https://github.com/LinkedSoftwareDependencies/Components.js/issues
- npm.io page: https://npm.io/package/componentsjs

## Dependencies (14)

- [semver](https://npm.io/package/semver.md) ^7.3.2
- [winston](https://npm.io/package/winston.md) ^3.3.3
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [rdf-quad](https://npm.io/package/rdf-quad.md) ^2.0.0
- [rdf-parse](https://npm.io/package/rdf-parse.md) ^4.0.0
- [rdf-terms](https://npm.io/package/rdf-terms.md) ^2.0.0
- [rdf-object](https://npm.io/package/rdf-object.md) ^3.0.0
- [rdf-string](https://npm.io/package/rdf-string.md) ^2.0.1
- [@types/node](https://npm.io/package/@types/node.md) ^18.0.0
- [@rdfjs/types](https://npm.io/package/@rdfjs/types.md) *
- [@types/semver](https://npm.io/package/@types/semver.md) ^7.3.4
- [@types/minimist](https://npm.io/package/@types/minimist.md) ^1.2.0
- [rdf-data-factory](https://npm.io/package/rdf-data-factory.md) ^2.0.2
- [jsonld-context-parser](https://npm.io/package/jsonld-context-parser.md) ^3.0.0

## Recent versions

- 6.4.0 (latest) — 2026-01-07
- 5.0.0-beta.7 (beta) — 2022-02-21
- 6.3.0 — 2024-10-23
- 6.2.0 — 2024-09-27
- 6.1.0 — 2024-09-17
- 6.0.1 — 2024-03-05
- 6.0.0 — 2024-03-04
- 5.5.1 — 2024-01-11
- 5.5.0 — 2024-01-09
- 5.4.2 — 2023-06-07
- 5.4.1 — 2023-05-23
- 5.4.0 — 2023-05-15
- 5.3.2 — 2022-11-14
- 5.3.1 — 2022-08-23
- 5.3.0 — 2022-08-04
- … 46 more at https://npm.io/package/componentsjs/versions

## README

# Components.js

_A semantic dependency injection framework_

[![Build status](https://github.com/LinkedSoftwareDependencies/Components.js/workflows/CI/badge.svg)](https://github.com/LinkedSoftwareDependencies/Components.js/actions?query=workflow%3ACI)
[![Coverage Status](https://coveralls.io/repos/github/LinkedSoftwareDependencies/Components.js/badge.svg)](https://coveralls.io/github/LinkedSoftwareDependencies/Components.js)
[![npm version](https://badge.fury.io/js/componentsjs.svg)](https://www.npmjs.com/package/componentsjs)
[![DOI](https://zenodo.org/badge/90724301.svg)](https://zenodo.org/badge/latestdoi/90724301)

This repository contains the source code of Components.js.
Full documentation on its usage can be found at http://componentsjs.readthedocs.io/.

Interested in contributing to this project?
Have a look at this [contribution guide](https://github.com/LinkedSoftwareDependencies/Components.js/blob/master/.github/CONTRIBUTING.md).

## Introduction

Components.js is a [dependency injection] framework for _TypeScript_ and _JavaScript_ projects using JSON(-LD) files.

Instead of hard-wiring software components together, Components.js allows these components to be _instantiated_ and _wired together_ declaratively using _semantic configuration files_.
The advantage of these semantic configuration files is that software components can be uniquely and globally identified using [URIs].

Configurations can be written in any [RDF] serialization, such as [JSON-LD].

This software is aimed for developers who want to build _modular_ and _easily configurable_ and _rewireable_ JavaScript applications.

Get started with the TypeScript or JavaScript quick start guide below!

## Quick Start (TypeScript)

#### 1. Install dependencies

Components.js can be installed using npm:
```bash
$ npm install componentsjs
```

Component and module files can be _automatically_ generated using [Components-Generator.js](https://github.com/LinkedSoftwareDependencies/Components-Generator.js):
```bash
$ npm install -D componentsjs-generator
```

#### 2. Mark your package as a Components.js module

`package.json`:
```json
{
  "name": "my-package",
  "version": "2.3.4",
  "lsd:module": true,
  "main": "index.js",
  "types": "index.d.ts",
  ...
  "scripts": {
    ...
    "build": "npm run build:ts && npm run build:components",
    "build:ts": "tsc",
    "build:components": "componentsjs-generator",
    "prepare": "npm run build",
    ...
  }
}
```

`"lsd:module"` will allow Components.js to find your module(s) when they are included from other packages.

The `"scripts"` entry will make sure that all required component files will be generated when building your package.

The `componentsjs-generator` will look for your compiled TypeScript files (`.d.ts`) in the `lib/` directory.
If you use a different output directory for TypeScript (e.g. `dist/`), you must pass this to the generator using `-s` flag (e.g. `componentsjs-generator -s dist`).

#### 3. Create a configuration file to instantiate our class

Assuming a TypeScript class that is exported from the package:
```typescript
export class MyClass {
  public readonly name: string;
  constructor(name: string) {
    this.name = name;  
  }
}
```

`config.jsonld`:
```json
{
  "@context": [
    "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^6.0.0/components/context.jsonld",
    "https://linkedsoftwaredependencies.org/bundles/npm/my-package/^2.0.0/components/context.jsonld"
  ],
  "@id": "urn:my-package:myInstance",
  "@type": "MyClass",
  "name": "John"
}
```

This configuration is a semantic representation of the instantiation of `MyClass` with `name` set to `"John"`.

#### 4. Instantiate from config file

```javascript
...
import { ComponentsManager } from 'componentsjs';

const manager = await ComponentsManager.build({
  mainModulePath: __dirname, // Path to your npm package's root
});
await manager.configRegistry.register('config.jsonld');
const myInstance = await manager.instantiate('urn:my-package:myInstance');
...
```

`myInstance` is an instance of type `MyClass`, as defined in the config file.

After running `npm run build`, you can now execute your program.

## Quick Start (JavaScript)

#### 1. Install dependencies

Components.js can be installed using npm:
```bash
$ npm install componentsjs
```

#### 2. Define your module and its components

Assuming a JavaScript class that is exported from the package:
```typescript
export class MyClass {
  public readonly name;
  constructor(name) {
    this.name = name;  
  }
}
```

`module.jsonld`:
```json
{
  "@context": [
    "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^6.0.0/components/context.jsonld",
    { "ex": "http://example.org/" }
  ],
  "@id": "ex:MyPackage",
  "@type": "Module",
  "requireName": "my-package",
  "components": [
    {
      "@id": "ex:MyPackage/MyClass",
      "@type": "Class",
      "requireElement": "MyClass",
      "parameters": [
        { "@id": "ex:MyPackage/MyClass#name", "unique": true }
      ],
      "constructorArguments": [
        { "@id": "ex:MyPackage/MyClass#name" }
      ]
    }
  ]
}
```

The npm module `my-package` exports a class with the name `MyClass`.

The constructor of `MyClass` takes a single `name` argument.

#### 3. Create a configuration file to instantiate our class

`config.jsonld`:
```json
{
  "@context": [
    "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^6.0.0/components/context.jsonld",
    {
      "ex": "http://example.org/",
      "name": "ex:MyPackage/MyClass#name"
    }
  ],
  "@id": "http://example.org/myInstance",
  "@type": "ex:MyPackage/MyClass",
  "name": "John"
}
```

This configuration is a semantic representation of the instantiation of `MyClass` with `name` set to `"John"`.

#### 4. Instantiate from config file

```javascript
...
import { ComponentsManager } from 'componentsjs';

const manager = await ComponentsManager.build({
  mainModulePath: __dirname, // Path to your npm package's root
});
await manager.configRegistry.register('config.jsonld');
const myInstance = await manager.instantiate('http://example.org/myInstance');
...
```

`myInstance` is an instance of type `MyClass`, as defined in the config file.

[Components.js]: https://github.com/LinkedSoftwareDependencies/Components.js
[GitHub]: https://github.com/LinkedSoftwareDependencies/Documentation-Components.js
[dependency injection]: https://martinfowler.com/articles/injection.html
[Node.js]: https://nodejs.org/en/
[URIs]: https://www.w3.org/wiki/URI
[RDF]: https://www.w3.org/RDF/
[JSON-LD]: https://json-ld.org/

## Advanced usage

The `ComponentsManager` can be customized with the following options:

```javascript
const manager = await ComponentsManager.build({
    // Absolute path to the package root from which module resolution should start.
    mainModulePath: __dirname,
    // Callback for registering components and modules
    // Defaults to an invocation of {@link ComponentRegistry.registerAvailableModules}.
    moduleLoader: (registry) => {},
    // Callback for registering configurations.
    // Defaults to no config registrations.
    configLoader: (registry) => {},
    // A strategy for constructing instances.
    // Defaults to {@link ConstructionStrategyCommonJs}.
    constructionStrategy: new ConstructionStrategyCommonJs(),
    // If the error state should be dumped into `componentsjs-error-state.json` after failed instantiations.
    // Defaults to `true`.
    dumpErrorState: true,
    // The logging level.
    // Defaults to `'warn'`.
    logLevel: 'warn',
    // The module state.
    // Defaults to a newly created instance on the {@link mainModulePath}.
    moduleState: {},
    // If JSON-LD context validation should be skipped.
    // Defaults to `true`.
    skipContextValidation: true,
    // If values for parameters should be type-checked.
    // Defaults to `true`.
    typeChecking: true,
});
```

## Cite

If you are using or extending Components.js as part of a scientific publication,
we would appreciate a citation of our [article](https://linkedsoftwaredependencies.github.io/Article-System-Components/).

```bibtex
@article{taelman_swj_componentsjs_2022,
  author = {Taelman, Ruben and Van Herwegen, Joachim and Vander Sande, Miel and Verborgh, Ruben},
  title = {Components.js: Semantic Dependency Injection},
  journal = {Semantic Web Journal},
  year = {2022},
  month = jan,
  url = {https://linkedsoftwaredependencies.github.io/Article-System-Components/}
}
```

## License
Components.js is written by [Ruben Taelman](http://www.rubensworks.net/).

This code is copyrighted by [Ghent University – imec](http://idlab.ugent.be/)
and released under the [MIT license](http://opensource.org/licenses/MIT).

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