{"id":17853,"library":"oc-client","title":"OC Client Node.js","description":"The `oc-client` package serves as a robust Node.js client for the OpenComponents micro-frontend framework, primarily facilitating server-side rendering of web components. It enables applications to consume, render, and manage distributed components from one or more registries. Key functionalities include instantiating a client with specific component versions and registry endpoints, warming up component caches, retrieving component metadata, and rendering components both individually and in batches. The current stable version is 4.0.2. The project is actively maintained and explicitly states it is under \"heavy development,\" indicating a potentially rapid release cadence and a higher likelihood of API changes between minor versions. Its core differentiator lies in providing a streamlined way to integrate OpenComponents into Node.js applications, offering features like cache management, request header forwarding, and flexible component versioning to efficiently display dynamic content.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/opencomponents/oc-client-node","tags":["javascript"],"install":[{"cmd":"npm install oc-client","lang":"bash","label":"npm"},{"cmd":"yarn add oc-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add oc-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Default template engine for OpenComponents, implicitly used if not overridden via the `templates` option.","package":"oc-template-handlebars","optional":true},{"reason":"Default template engine for OpenComponents, implicitly used if not overridden via the `templates` option.","package":"oc-template-jade","optional":true}],"imports":[{"note":"In CommonJS, the `Client` constructor is the direct default export of the package. Do not destructure `Client` from the `require()` call.","wrong":"const { Client } = require('oc-client');","symbol":"Client","correct":"const Client = require('oc-client');"},{"note":"For ES Modules, `Client` is the default export of the package. Named imports are not supported for the main Client class.","wrong":"import { Client } from 'oc-client';","symbol":"Client (ESM)","correct":"import Client from 'oc-client';"}],"quickstart":{"code":"const Client = require('oc-client');\n\nconst client = new Client({\n  registries: { serverRendering: 'https://myregistry.com/' }, // IMPORTANT: Replace with your actual OpenComponents registry URL\n  components: {\n    // Define components your application will consume with desired versions\n    headerComponent: '1.2.3',\n    footerComponent: '~2.2.5'\n  },\n  cache: {\n    flushInterval: 60 * 5 // Optional: Cache invalidation interval in seconds (e.g., 5 minutes)\n  }\n});\n\nclient.init({\n  // Optional: Headers to forward during component warm-up requests\n  headers: {\n    'accept-language': 'en-US,en;q=0.9',\n    'user-agent': 'Mozilla/5.0 (Node.js) oc-client-app'\n  },\n  timeout: 10 // Optional: Maximum request time in seconds\n}, function(error, responses){\n  if (error) {\n    console.error('oc-client initialization failed:', error);\n    // Implement robust error handling, e.g., serve a fallback or retry\n  } else {\n    console.log('oc-client initialized successfully. Warm-up responses:', responses);\n  }\n\n  // Example: Render a single component\n  client.renderComponent('headerComponent', {\n    headers: { 'x-trace-id': 'req-123' },\n    parameters: { title: 'Welcome to My App' }\n  }, function(err, htmlResponse) {\n    if (err) {\n      console.error('Failed to render headerComponent:', err);\n    } else {\n      console.log('Successfully rendered headerComponent:', htmlResponse.html);\n      // htmlResponse.html contains the rendered HTML string\n      // htmlResponse.assets contains client-side assets (CSS, JS) if any\n    }\n  });\n});","lang":"javascript","description":"Demonstrates initializing the `oc-client` with registry and component configurations, warming up components, and rendering a single component."},"warnings":[{"fix":"Thoroughly review release notes and test suite updates with each new version. Pin dependencies to exact versions in your `package.json` to prevent unexpected breakage (`\"oc-client\": \"4.0.2\"`).","message":"The project is explicitly labeled as 'still under heavy development' and its API is 'likely to change at any time'. This indicates that breaking changes can occur frequently even in minor or patch releases.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment is version 12 or newer to meet the package's declared engine requirements, overriding the outdated README advice.","message":"The README states 'Node.js version: **6** required', while `package.json` for version 4.0.2 specifies `\"node\": \">=12\"`. Always defer to the `package.json` `engines` field (`>=12`) for current compatibility. Using Node.js versions older than 12 with this package may lead to unexpected behavior or errors, despite the README's outdated advice.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that `registries.serverRendering` is provided in the Client constructor options and points to a valid OpenComponents registry URL (e.g., `{ registries: { serverRendering: 'https://your-registry.com/' } }`).","message":"Missing or incorrect `registries` configuration is a common cause of errors, leading to the client being unable to fetch components. The `serverRendering` property within `registries` is mandatory for server-side operations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Use the ES Module `import` syntax: `import Client from 'oc-client';`.","cause":"Attempting to use CommonJS `require()` syntax (e.g., `const Client = require('oc-client');`) in an ES Module context (e.g., in a file with `\"type\": \"module\"` in `package.json` or a `.mjs` file).","error":"ReferenceError: require is not defined"},{"fix":"Double-check that the `registries.serverRendering` URL provided to the `Client` constructor is correct and accessible from your Node.js application. Verify network connectivity and ensure the OpenComponents registry service is running and healthy. Inspect registry logs for specific error details.","cause":"The `oc-client` failed to connect to or receive a valid response from the configured OpenComponents registry, often due to an incorrect registry URL, network issues, or an unresponsive registry service.","error":"Error making request to registry"},{"fix":"Ensure the `registries` object is passed to the `Client` constructor and contains at least a `serverRendering` URL: `new Client({ registries: { serverRendering: 'https://your-registry.com/' }, ... });`.","cause":"The `registries` object was either not provided or was empty in the `Client` constructor options, but the client attempted to access `registries.serverRendering`, which is a mandatory configuration.","error":"TypeError: Cannot read properties of undefined (reading 'serverRendering')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}