Generate standardized specifications for your web components automatically. OWCS analyzes your Angular and React components and creates documentation and configuration files that help you share and use components across projects.
This project is organized as an Nx monorepo with four packages:
- @owcs/schemas - JSON Schema definitions and validation utilities
- @owcs/api - Core API for analyzing components and generating specifications
- @owcs/cli - Command-line interface
- @owcs/ui - Web component for visualizing OWCS specifications
OWCS creates detailed specifications from your existing web components, including:
- Component properties (inputs/props) with types and validation
- Events (outputs/callbacks) that components emit
- Module federation configuration for micro-frontends
- OpenAPI documentation for integration
- Support for multiple frameworks: Angular, React (with more coming)
pnpm add -g @owcs/cliOr use directly with npx:
npx @owcs/cli generate --adapter angular- Node.js 18+
- TypeScript project with Angular or React components
Generate a specification from your Angular project:
npx @owcs/cli generate --adapter angularGenerate a specification from your React project:
npx @owcs/cli generate --adapter reactThis creates an owcs.yaml file describing your components.
Common options:
# Generate JSON instead of YAML
npx @owcs/cli generate --adapter react --format json
# Specify output file
npx @owcs/cli generate --adapter angular --output my-components.yaml
# Also create OpenAPI documentation
npx @owcs/cli generate --adapter react --openapi
# Validate an existing specification
npx @owcs/cli validate owcs.yamlCreate an owcs.config.js or owcs.config.json file to set defaults for all CLI options. CLI arguments always override config values.
// owcs.config.js
export default {
// Specification metadata
title: 'My Components',
description: 'A collection of reusable web components',
version: '2.0.0',
// Build options
adapter: 'react', // 'angular' or 'react'
format: 'yaml', // 'yaml' or 'json'
outputPath: './dist/owcs.yaml',
projectRoot: './src',
includeRuntimeExtension: true,
// Custom vendor extensions (all keys must start with 'x-')
extensions: {
'x-owner': 'platform-team',
'x-team-name': 'Frontend Core',
'x-git-repo': 'https://github.com/org/repo',
},
};With a config file, you can run:
# Use all config defaults
npx @owcs/cli generate
# Override specific options
npx @owcs/cli generate --title "Custom Title" --format jsonSupported config formats: owcs.config.js, owcs.config.mjs, owcs.config.cjs, owcs.config.json
Note: The CLI looks for the config file in the project root directory (specified by the -p, --project option or the current working directory by default).
If you need to generate specifications programmatically, install the API package:
pnpm add @owcs/apiimport { analyzeAngularProject, buildOWCSSpec, writeOWCSSpec } from '@owcs/api';
// Analyze your Angular project
const analysis = analyzeAngularProject('./src');
// Build specification
const spec = buildOWCSSpec(analysis, {
title: 'My Angular Components',
version: '1.0.0',
extensions: {
'x-owner': 'platform-team',
'x-version': '2.0.0',
},
});
// Save to file
writeOWCSSpec(spec, 'owcs.yaml', 'yaml');import { analyzeReactProject, buildOWCSSpec, writeOWCSSpec, loadConfig } from '@owcs/api';
// Analyze your React project
const analysis = analyzeReactProject('./src');
// Optionally load extensions from config file
const config = await loadConfig('./my-project');
// Build specification
const spec = buildOWCSSpec(analysis, {
title: 'My React Components',
version: '1.0.0',
extensions: config?.extensions,
});
// Save to file
writeOWCSSpec(spec, 'owcs.yaml', 'yaml');OWCS examines your Angular components and extracts:
// Finds web component definitions
customElements.define('user-card', UserCardComponent);@Input() name: string; // Required string property
@Input() age?: number; // Optional number property
@Input('userId') id: string; // Property with custom attribute name@Output() clicked = new EventEmitter<{userId: string}>();
// Also detects custom events.
this.dispatchEvent(new CustomEvent('userChanged', {
detail: { name: 'John', age: 30 }
}));OWCS examines your React components wrapped as Web Components:
customElements.define('user-card', UserCardWC);interface UserCardProps {
name: string; // Required string property
age?: number; // Optional number property
theme: 'light' | 'dark'; // Union type (enum)
config?: { // Object type
showAvatar: boolean;
};
}
const UserCard: React.FC<UserCardProps> = (props) => {
return <div>{props.name}</div>;
};interface UserCardProps {
onClick?: (event: { userId: string }) => void; // Callback prop
onHover?: () => void;
}
// Or custom event dispatch
const handleClick = () => {
const event = new CustomEvent('userClick', {
detail: { userId: '123' },
});
dispatchEvent(event);
};// Extracted from webpack.config.js
new ModuleFederationPlugin({
name: 'userComponents',
exposes: {
'./UserCard': './src/user-card.component.ts',
},
});OWCS creates a YAML file that describes your components:
owcs: 1.0.0
info:
title: My Components
version: 1.0.0
x-owner: platform-team
x-package-version: 2.0.0
x-team-name: Frontend Core
x-git-repo: https://github.com/org/repo
x-owcs-runtime:
bundler:
name: webpack
moduleFederation:
remoteName: userComponents
exposes:
./UserCard: ./src/user-card.component.ts
components:
webComponents:
user-card:
tagName: user-card
module: ./UserCard
props:
schema:
type: object
properties:
name:
type: string
age:
type: number
required: [name]
events:
clicked:
type: CustomEvent
payload:
type: object
properties:
userId:
type: stringConvert your component specification to OpenAPI format for API documentation:
npx @owcs/cli generate --openapiThis creates both owcs.yaml and openapi.yaml files, making your components discoverable by API documentation tools like Swagger UI.
The @owcs/ui package provides a beautiful web component for displaying OWCS specifications in a user-friendly, interactive format.
npm install @owcs/ui<!DOCTYPE html>
<html>
<head>
<script type="module" src="node_modules/@owcs/ui/dist/owcs-viewer.js"></script>
</head>
<body>
<!-- Load from inline YAML -->
<owcs-viewer yaml="owcs: 1.0.0..."></owcs-viewer>
<!-- Or load from URL -->
<owcs-viewer yaml-url="/path/to/owcs.yaml"></owcs-viewer>
</body>
</html>- Beautiful UI: Professional, modern design with gradient headers and smooth animations
- Search & Filter: Real-time search to filter components by tag name
- TypeScript Code Generation: Automatically displays props and events as TypeScript code
- Schema Validation: Built-in OWCS schema validation
- Responsive Design: Works on all screen sizes
- Extensions Display: Shows all custom vendor extensions
cd apps/owcs-viewer-demo
npm run devThis will launch an interactive demo where you can see the OWCS viewer in action with the Angular example specification.
For more details, see the @owcs/ui README.
| Command | Description |
|---|---|
owcs generate |
Generate specification from your project (Angular or React) |
owcs validate <file> |
Check if a specification file is valid |
owcs info <file> |
Show details about a specification file |
All options can be set in owcs.config.js or provided via CLI. CLI options override config values.
-a, --adapter <adapter>- Framework adapter:angularorreact(default:angular)-f, --format <format>- Output format:yamlorjson(default:yaml)-o, --output <file>- Output file path (default:owcs.yaml)-p, --project <path>- Project root directory (default: current directory)-t, --tsconfig <path>- Path to tsconfig.json--title <title>- Specification title--version <version>- Specification version (default:1.0.0)--description <description>- Specification description--openapi- Also generate OpenAPI specification
Note: includeRuntimeExtension and extensions options are only available via the config file and are automatically applied when present.
This project uses Nx for monorepo management.
# Clone the repository
git clone https://github.com/RakeshPawar/OWCS.git
cd OWCS
# Install dependencies
pnpm install# Build all packages
pnpm run build
# Build specific package
npx nx build schemas
npx nx build api
npx nx build cli# Run all tests
pnpm test
# Test specific package
npx nx test schemas
npx nx test api# Lint all packages
pnpm run lint
# Lint specific package
npx nx lint apipackages/schemas- JSON Schema definitionspackages/api- Core analysis and spec generationpackages/cli- CLI application (bundled for publishing)packages/ui- Web component for visualizing OWCS specsapps/*-example- Example applications for testingapps/owcs-viewer-demo- Demo app for the UI component
Test the CLI with example applications:
# Generate specs for examples
npx nx generate-spec angular-example
npx nx generate-spec react-vite-example
npx nx generate-spec react-webpack-exampleWant to help improve OWCS? Contributions are welcome! The project is designed to support multiple frameworks:
- Add framework support - Create adapters for Vue, Svelte, or other frameworks
- Enhance existing adapters - Add features like template parsing or CSS custom properties
- Improve documentation - Help make the docs even more user-friendly
See CONTRIBUTING.md for development setup and guidelines.
Note: This project uses Conventional Commits with commitlint to ensure consistent commit messages. Please read docs/COMMIT_GUIDELINES.md before making commits.
MIT License - see LICENSE file for details.