Introduction

For modular projects, it can be useful to define components across different npm modules.

For example, a certain npm module can allow plugins to be injected. Using Components.js, plugins could be defined using declarative components, and this npm module could dynamically inject these components as configured by the user. In order to do this, only the main project that needs to instantiate the components needs to depend on Components.js. The other components, i.e. plugins, only need to expose their component files.

Package.json discovery

Components.js can automatically discover components if they are defined in the package.json file of npm modules. The URI of the module and a link to its module file needs to be defined. For example:

{
  "name": "my-plugin",
  ...
  "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/my-plugin",
  "lsd:components": "components/components.jsonld",
  ...
}

Advanced: Context overriding

Optionally, a JSON-LD context file can be linked as well, which allows this context to be dereferenced locally:

{
  "lsd:contexts": {
    "http://example.org/mycontext.jsonld": "components/context.jsonld"
  },
}

Note

By default, JSON-LD parsers will attempt to fetch all linked contexts. As this can lead to some overhead, Components.js can automatically wire contexts together if they are defined in package.json files. Instead of resolving the context via HTTP(S), the context will be fetched from the local file system instead, as defined by the npm modules.

Note

If your package is available on npm, and you have properly used the lsd:components entry in your package.json file, then your context file will automatically be published on the Linked Software Dependencies npm mirror. The URL of your context file is https://linkedsoftwaredependencies.org/bundles/npm/[packagename]/[version or range]/components/context.jsonld. For example, the latest context file of Components.js is available at https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/*/components/context.jsonld. In that case, you are encouraged to use these URLs as keys lsd:contexts.

Advanced: Import overriding

Similar to context file overriding, import paths can also be overridden. This is useful when you want to avoid expensive HTTP lookups for files in cases where you have the relevant files available locally. Additionally, this can be used during development when you make changes to your imported file that has not been made available via its URL (yet).

The lsd:importPaths refers to a hash that maps URL prefixes to local path prefixes:

{
  "lsd:importPaths": {
    "http://example.org/myconfig.jsonld": "config/myconfig.jsonld",
    "http://example.org/otherconfigs/": "config/otherconfigs/",
  },
}

Note

If your package is available on npm, then your import paths will automatically be published on the Linked Software Dependencies npm mirror. The URL of this will be https://linkedsoftwaredependencies.org/bundles/npm/[packagename]/[version or range]/[importPathValue]. For example, the latest version of @comunica/actor-init-hello-world with import path value config/ will be exposed at https://linkedsoftwaredependencies.org/bundles/npm/@comunica/actor-init-hello-world/*/config/. In that case, you are encouraged to use these URLs as keys lsd:importPaths.