{"id":14778,"library":"oc-server-compiler","title":"OpenComponents Server-Side Logic Compiler","description":"oc-server-compiler is a foundational module within the OpenComponents (OC) micro-frontends framework, designed specifically to compile the server-side logic (`server.js` or `entry.server.ts`) of isomorphic OC components. These components encapsulate HTML, CSS, JavaScript, and optional server-side code, allowing for universal rendering. This package facilitates the transformation of a component's server-side JavaScript/TypeScript into an executable format, typically used by an OC registry for server-side rendering or by the OC CLI during component development and publishing. It is a core utility that ensures the component's data-fetching and model-composition logic is correctly processed for deployment. The current stable version is 4.0.0. While the OpenComponents project itself follows semantic versioning with releases driven by feature development and bug fixes, this compiler module's updates are tightly coupled with the broader framework's evolution. A key differentiator of OpenComponents is its language-agnostic approach to consumption, allowing components compiled by this module to be rendered and consumed by various backend technologies (e.g., C#, PHP, Java, Go) without requiring Node.js on the edge.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/opencomponents/base-templates","tags":["javascript","oc","opencomponents","typescript"],"install":[{"cmd":"npm install oc-server-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add oc-server-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add oc-server-compiler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `compile` function is the primary programmatic interface for transforming server-side component logic. While OpenComponents is moving towards ESM, CommonJS is still common in Node.js environments. Use named import as shown.","wrong":"const { compile } = require('oc-server-compiler');","symbol":"compile","correct":"import { compile } from 'oc-server-compiler';"},{"note":"This package ships with TypeScript types. Import `CompilerOptions` to type-check configuration objects for the `compile` function.","symbol":"CompilerOptions","correct":"import type { CompilerOptions } from 'oc-server-compiler';"},{"note":"In some OpenComponents contexts, the compiler might be instantiated as a class or have a default export, though `compile` is the most common direct usage. Verification of this specific export is recommended.","symbol":"OcCompiler","correct":"import OcCompiler from 'oc-server-compiler';"}],"quickstart":{"code":"import { compile } from 'oc-server-compiler';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nasync function runCompilation() {\n  const componentPath = path.join(process.cwd(), 'my-component');\n  const serverJsPath = path.join(componentPath, 'server.js');\n  const componentPackageJsonPath = path.join(componentPath, 'package.json');\n\n  // Create a dummy component directory and files for demonstration\n  if (!fs.existsSync(componentPath)) {\n    fs.mkdirSync(componentPath, { recursive: true });\n  }\n  fs.writeFileSync(serverJsPath, `\n    module.exports = { \n      data: (context, callback) => {\n        console.log('Executing server.js data function...');\n        callback(null, { name: context.params.name || 'World', version: '4.0.0' });\n      }\n    };\n  `);\n  fs.writeFileSync(componentPackageJsonPath, `\n    {\n      \"name\": \"my-component\",\n      \"version\": \"1.0.0\",\n      \"oc\": {\n        \"files\": {\n          \"data\": \"server.js\",\n          \"template\": {\n            \"src\": \"template.html\",\n            \"type\": \"handlebars\"\n          }\n        }\n      }\n    }\n  `);\n\n  try {\n    // The compile function takes the component's directory path\n    // and returns compiled assets or metadata.\n    const result = await compile({\n      componentPath: componentPath,\n      minify: true,\n      verbose: process.env.DEBUG === 'true'\n    });\n    console.log('Compilation successful! Output:');\n    console.log(JSON.stringify(result, null, 2));\n    // Expected result might include: { entry: 'compiled/server.js', hash: '...', externals: [] }\n  } catch (error) {\n    console.error('Compilation failed:', error);\n  } finally {\n    // Clean up dummy files\n    fs.unlinkSync(serverJsPath);\n    fs.unlinkSync(componentPackageJsonPath);\n    fs.rmdirSync(componentPath);\n  }\n}\n\nrunCompilation();\n","lang":"typescript","description":"This quickstart demonstrates how to programmatically use `oc-server-compiler` to compile a mock OpenComponents `server.js` file, simulating the build process for component server logic."},"warnings":[{"fix":"Upgrade your Node.js environment to version 12 or newer. Node.js 18 LTS or later is strongly recommended for OpenComponents development and production.","message":"Starting with OpenComponents v0.49.0, Node.js versions 8 and 10 are no longer supported. `oc-server-compiler` as a core module in version 4.0.0 requires Node.js 12 or higher, with Node.js 18+ being recommended for optimal performance and security. Running on older Node.js versions will likely lead to errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure that files passed to the compiler adhere to the OpenComponents component specification, particularly the structure expected for a component's server-side logic. Use the `oc` CLI for standard component development workflows.","message":"The `oc-server-compiler` is part of the OpenComponents ecosystem and is not a general-purpose JavaScript/TypeScript compiler. It expects specific input structures conforming to the OpenComponents component specification (e.g., `server.js` within an OC component directory). Attempting to compile arbitrary JavaScript or TypeScript files directly without the correct context will result in errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review and update component templates and server-side logic to use modern JavaScript/TypeScript and template engine features. Consult the OpenComponents migration guides for specifics on template updates if issues arise.","message":"Older OpenComponents templates (e.g., specific Handlebars or Jade versions) might be compiled with older internal compiler logic or rely on deprecated features. While `oc-server-compiler` 4.0.0 handles modern ES6 templates by default and aims for backward compatibility, using outdated template syntax in conjunction with server-side logic could lead to unexpected behavior or compilation warnings.","severity":"deprecated","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"When calling the `data` function directly or through a mock, ensure the `context` object is fully populated with all expected properties, including `params` and `headers`, as defined by the OpenComponents runtime environment.","cause":"The `context` object provided to a component's server-side `data` function is missing expected properties, such as `params`, which typically come from a client request.","error":"TypeError: Cannot read properties of undefined (reading 'params')"},{"fix":"If your `server.js` is intended to be an ESM module, ensure your `package.json` specifies `\"type\": \"module\"` in the component directory, or explicitly use `.mjs` extension. Otherwise, use CommonJS `module.exports = { ... };` syntax for compatibility.","cause":"The `server.js` file uses ESM `export` syntax (e.g., `export function data() { ... }`) but is being treated as CommonJS by the compiler or the Node.js runtime.","error":"Error: Component server.js compilation failed: SyntaxError: Unexpected token 'export'"},{"fix":"Ensure all server-side dependencies for the component are correctly installed (e.g., `npm install` in the component's directory) and accessible in the compilation environment. If publishing, confirm the registry supports resolving or bundles these dependencies.","cause":"A server-side dependency declared in the component's `package.json` (or required in `server.js`) cannot be resolved during compilation or runtime.","error":"Error: Cannot find module 'some-external-dependency' from '...' at Function.Module._resolveFilename"}],"ecosystem":"npm"}