Registry / web-framework / oc-server-compiler

oc-server-compiler

JSON →
library4.0.0jsnpmunverified

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.

npm install oc-server-compiler
INSTALL
IMPORT
SIG · OC-SERVER-COMPILER
O
oc-server-compiler
web-frameworkjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

compile
import { compile } from 'oc-server-compiler';
const { compile } = require('oc-server-compiler');
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.
CompilerOptions
import type { CompilerOptions } from 'oc-server-compiler';
This package ships with TypeScript types. Import `CompilerOptions` to type-check configuration objects for the `compile` function.
OcCompiler
import OcCompiler from 'oc-server-compiler';
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.

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.

import { compile } from 'oc-server-compiler'; import * as fs from 'fs'; import * as path from 'path'; async function runCompilation() { const componentPath = path.join(process.cwd(), 'my-component'); const serverJsPath = path.join(componentPath, 'server.js'); const componentPackageJsonPath = path.join(componentPath, 'package.json'); // Create a dummy component directory and files for demonstration if (!fs.existsSync(componentPath)) { fs.mkdirSync(componentPath, { recursive: true }); } fs.writeFileSync(serverJsPath, ` module.exports = { data: (context, callback) => { console.log('Executing server.js data function...'); callback(null, { name: context.params.name || 'World', version: '4.0.0' }); } }; `); fs.writeFileSync(componentPackageJsonPath, ` { "name": "my-component", "version": "1.0.0", "oc": { "files": { "data": "server.js", "template": { "src": "template.html", "type": "handlebars" } } } } `); try { // The compile function takes the component's directory path // and returns compiled assets or metadata. const result = await compile({ componentPath: componentPath, minify: true, verbose: process.env.DEBUG === 'true' }); console.log('Compilation successful! Output:'); console.log(JSON.stringify(result, null, 2)); // Expected result might include: { entry: 'compiled/server.js', hash: '...', externals: [] } } catch (error) { console.error('Compilation failed:', error); } finally { // Clean up dummy files fs.unlinkSync(serverJsPath); fs.unlinkSync(componentPackageJsonPath); fs.rmdirSync(componentPath); } } runCompilation();
Debug
Known issues
breakingStarting 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.
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.
affects: >=4.0.0
gotchaThe `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.
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.
affects: >=1.0.0
deprecatedOlder 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.
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.
affects: <4.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'params')
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.
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.
Error: Component server.js compilation failed: SyntaxError: Unexpected token 'export'
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.
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.
Error: Cannot find module 'some-external-dependency' from '...' at Function.Module._resolveFilename
A server-side dependency declared in the component's `package.json` (or required in `server.js`) cannot be resolved during compilation or runtime.
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.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
oc-server-compiler — npm install oc-server-compiler · libregistry