oc
v0.50.67
Published
A framework for developing and distributing html components
Readme
OpenComponents, serverless in the front-end world.
OpenComponents is an open-source framework that allows fast-moving teams to easily build and deploy front-end components. It abstracts away complicated infrastructure and leaves developers with very simple, but powerful building blocks that handle scale transparently.
How does it work?
First, you create your component. It can contain logic to get some data (using node.js) and then the view, including css and js. It can be what you want, including React or Angular components or whatever you like.
Then, you publish it to the OpenComponents registry and you wait a couple of seconds while the registry prepares your stuff to be production-ready.
Now, every web app in your private or public network can consume the component via its own HTTP endpoint during server-side rendering or just in the browser.
We have been using it for more than two years in production at OpenTable, for shared components, third party widgets, e-mails and more. Learn more about OC.
Links
- Website
- Documentation
- Requirements and build status
- Changelog
- Awesome resources about OC
- Contributing guidelines
- Code of conduct
- Troubleshooting
- Gitter chat
Registry metadata stores
By default, an OC registry keeps its component index in storage files:
components.json and components-details.json. A registry can instead read and
write that index through a metadata adapter by adding a metadata block to the
registry configuration.
Storage is still required in metadata mode. The metadata store contains only the
component name, version, publish date, and template size. Component static files
and version package.json files continue to live in the configured storage
adapter.
const azureSqlMetadataAdapter = require('oc-azure-sql-metadata-adapter').default;
const s3StorageAdapter = require('oc-s3-storage-adapter');
registry.configure({
storage: {
adapter: s3StorageAdapter,
options: {
bucket: process.env.OC_STORAGE_BUCKET,
region: process.env.OC_STORAGE_REGION,
componentsDir: 'components',
path: process.env.OC_STORAGE_BASE_URL
}
},
metadata: {
adapter: azureSqlMetadataAdapter,
options: {
connectionString: process.env.OC_METADATA_SQL_CONNECTION_STRING
},
manageSchema: true,
reconcileFromStorage: false,
exportLegacyFiles: false
}
});metadata.manageSchema defaults to true. Set it to false when operators
manage the metadata schema/table separately; OC passes the value through to the
configured metadata adapter during validation, startup, and migration.
The registry initialises the metadata store during startup. If startup succeeds,
reads are served from OC's in-memory cache, and cache polling refreshes from the
metadata store. Publishing reserves the metadata row first, uploads package files
to storage only after the reservation succeeds, then commits the row. Duplicate
or in-progress metadata rows are treated as the existing "component version
already exists" publish error. When the registry is shut down via
registry.close(callback), the metadata adapter's optional close() hook is
invoked so the adapter can release its connection pool.
Custom metadata adapters should implement the shared contract exported by
oc-metadata-adapters-utils:
import type { ComponentRow, MetadataStore } from 'oc-metadata-adapters-utils';
import {
VERSION_ALREADY_EXISTS,
VERSION_PUBLISH_IN_PROGRESS
} from 'oc-metadata-adapters-utils';Migrating existing registries
Use the CLI backfill command before enabling metadata mode in production:
oc registry migrate-metadata ./registry.config.jsThe argument is a path to a module that exports the same registry config object you would pass to registry.configure(). It must include both storage and metadata, and it must pass registry config validation. The module can be CommonJS, an ES module default export, or an async function returning the config — all three are accepted:
// registry.config.js — CommonJS
const azureSqlMetadataAdapter = require('oc-azure-sql-metadata-adapter').default;
const s3StorageAdapter = require('oc-s3-storage-adapter');
module.exports = {
baseUrl: 'http://my-registry.example.com/',
storage: {
adapter: s3StorageAdapter,
options: {
bucket: 'my-bucket',
region: 'us-east-1',
componentsDir: 'components',
path: 'https://cdn.example.com/'
}
},
metadata: {
adapter: azureSqlMetadataAdapter,
options: {
connectionString: process.env.OC_METADATA_SQL_CONNECTION_STRING
}
}
};// registry.config.ts — ES module (transpiled or run with a native ESM loader)
import azureSqlMetadataAdapter from 'oc-azure-sql-metadata-adapter';
import s3StorageAdapter from 'oc-s3-storage-adapter';
export default {
baseUrl: 'http://my-registry.example.com/',
storage: {
adapter: s3StorageAdapter,
options: {
bucket: 'my-bucket',
region: 'us-east-1',
componentsDir: 'components',
path: 'https://cdn.example.com/'
}
},
metadata: {
adapter: azureSqlMetadataAdapter,
options: {
connectionString: process.env.OC_METADATA_SQL_CONNECTION_STRING
}
}
};// registry.config.js — async factory (e.g. to resolve secrets first)
module.exports = async () => {
const azureSqlMetadataAdapter = require('oc-azure-sql-metadata-adapter').default;
const s3StorageAdapter = require('oc-s3-storage-adapter');
const connectionString = await getSecret('oc-metadata-sql');
return {
baseUrl: 'http://my-registry.example.com/',
storage: {
adapter: s3StorageAdapter,
options: {
bucket: 'my-bucket',
region: 'us-east-1',
componentsDir: 'components',
path: 'https://cdn.example.com/'
}
},
metadata: {
adapter: azureSqlMetadataAdapter,
options: { connectionString }
}
};
};The command initialises the configured metadata adapter and backfills rows from
${componentsDir}/components-details.json. If that file is missing, it falls back
to scanning ${componentsDir}/<component>/<version>/package.json. Existing rows
are skipped, so the command is idempotent.
A safe migration sequence is:
- Deploy the metadata adapter configuration to a non-serving environment.
- Run
oc registry migrate-metadata ./registry.config.js. - Start one registry instance with metadata mode enabled and verify reads.
- Roll out metadata mode to the remaining registry instances.
Bake-in and rollback options
Two optional flags help run storage and metadata side by side during migration:
metadata.reconcileFromStorage: truescans storage on registry startup and inserts missing metadata rows before cache hydration. Existing rows are skipped.metadata.exportLegacyFiles: truewrites DB-derivedcomponents.jsonandcomponents-details.jsonprojections to storage once on registry startup. It is not triggered per publish, so publishing stays an O(1) append rather than a full-registry scan + blob rewrite.metadata.exportLegacyFilesInterval: <seconds>additionally refreshes those projections on a background timer (non-overlapping) whenexportLegacyFilesis enabled. Config validation rejects setting an interval withoutmetadata.exportLegacyFiles: true. Omit it to export at startup only. The timer is stopped onregistry.close().
These files are one-way projections from the metadata store. They can help with rollback to storage mode, but they do not replace the storage adapter because component statics remain in storage.
Registry events
The registry emits an error event with the stable payload shape
{ code: string, message: string }:
registry.on('error', ({ code, message }) => {
console.error(code, message);
});Errors raised by the configured server adapter use the adapter-neutral code
SERVER_ERROR. The message is preserved from the adapter error, and the existing
start callback and promise rejection behavior is unchanged. The public
TypeScript payload is exported as RegistryErrorEvent.
Requirements and build status
Disclaimer: This project is still under heavy development and the API is likely to change at any time. In case you would find any issues, check the troubleshooting page.
License
MIT

