Skip to main content

Structure of package.json

Overview

The package.json file is the heart of your OpenComponents component configuration. It defines not only standard npm package information but also OpenComponents-specific settings that control how your component is built, rendered, and consumed.

Essential vs Optional Parameters

✅ Essential Parameters (Required)

These parameters are required for every OpenComponents component:

{
"name": "hello-world", // Required: Component name
"version": "1.0.0", // Required: Semantic version
"oc": { // Required: OpenComponents config
"files": { // Required: File definitions
"template": { // Required: Template config
"src": "template.js", // Required: Template file
"type": "oc-template-es6" // Required: Template type
}
}
},
"devDependencies": { // Required: Template compiler
"oc-template-es6-compiler": "6.0.8"
}
}

These parameters enhance your component's functionality and documentation:

{
"description": "A reusable header component", // Recommended: Clear description
"author": "John Doe <john@doe.com>", // Recommended: Author info
"repository": "https://github.com/...", // Recommended: Source repo
"oc": {
"files": {
"data": "server.js", // Optional: Server-side logic
"static": ["public", "assets"] // Optional: Static assets
},
"parameters": { // Recommended: API documentation
"title": {
"type": "string",
"mandatory": true,
"description": "The header title to display"
}
}
}
}

Complete Example Templates

Basic Static Component

For simple components without server-side logic:

{
"name": "simple-banner",
"description": "A static promotional banner component",
"version": "1.0.0",
"author": "Your Team <team@company.com>",
"repository": "https://github.com/company/components",
"oc": {
"files": {
"template": {
"src": "template.js",
"type": "oc-template-es6"
},
"static": ["public"]
},
"parameters": {
"message": {
"type": "string",
"mandatory": true,
"description": "Banner message to display",
"example": "Special offer - 20% off!"
},
"variant": {
"type": "string",
"mandatory": false,
"default": "primary",
"description": "Banner style variant",
"example": "primary"
}
},
"state": "active"
},
"devDependencies": {
"oc-template-es6-compiler": "6.0.8"
}
}

Dynamic Component with Server Logic

For components that fetch data or perform server-side processing:

{
"name": "user-profile",
"description": "Dynamic user profile component with API integration",
"version": "2.1.0",
"author": "Frontend Team <frontend@company.com>",
"repository": "https://github.com/company/user-components",
"dependencies": {
"axios": "^1.0.0",
"lodash": "^4.17.21"
},
"oc": {
"files": {
"data": "server.js",
"template": {
"src": "template.js",
"type": "oc-template-es6"
},
"static": ["public", "assets"]
},
"parameters": {
"userId": {
"type": "string",
"mandatory": true,
"description": "User ID to fetch profile for",
"example": "user123"
},
"showAvatar": {
"type": "boolean",
"mandatory": false,
"default": true,
"description": "Whether to display user avatar"
},
"theme": {
"type": "string",
"mandatory": false,
"default": "light",
"description": "Component theme",
"example": "dark"
}
},
"plugins": ["oc-plugin-hash"],
"state": "active",
"renderInfo": true
},
"devDependencies": {
"oc-template-es6-compiler": "6.0.8"
}
}

Complete Parameter Reference

Standard npm Parameters

ParameterTypeRequiredDescription
namestringRequiredComponent name (must be unique in registry). Use kebab-case format
versionstringRequiredSemantic version (e.g., "1.0.0"). Follow semver
descriptionstring🔧 RecommendedClear, concise component description for documentation
authorstring🔧 RecommendedAuthor info: "John Doe <john@doe.com>"
repositorystring🔧 RecommendedGit repository URL for source code
dependenciesobjectOptionalnpm modules required at runtime
devDependenciesobjectRequiredDevelopment dependencies (always include template compiler)

OpenComponents Configuration (oc)

ParameterTypeRequiredDescription
ocobjectRequiredMain OpenComponents configuration object

File Configuration (oc.files)

ParameterTypeRequiredDescription
oc.filesobjectRequiredDefines component file structure
oc.files.templateobjectRequiredTemplate configuration
oc.files.template.srcstringRequiredTemplate filename (e.g., "template.js")
oc.files.template.typestringRequiredTemplate type: "oc-template-es6" (default), "oc-template-react", etc.
oc.files.datastringOptionalServer-side logic filename (default: "server.js")
oc.files.staticarrayOptionalStatic asset directories (e.g., ["public", "assets"])
oc.files.envstringOptionalEnvironment variables file path

Component Behavior

ParameterTypeRequiredDescription
oc.containerbooleanOptionalIf true, renders without <oc-component> wrapper (default: false)
oc.minifybooleanOptionalMinify CSS/JS during publishing (default: true)
oc.renderInfobooleanOptionalInclude component info in rendered output (default: true)
oc.statestring🔧 RecommendedComponent lifecycle: "active", "experimental", "deprecated"

API Documentation (oc.parameters)

ParameterTypeRequiredDescription
oc.parametersobject🔧 RecommendedComponent API definition for validation and docs
oc.parameters[key].typestringRequiredParameter type: "string", "boolean", "number"
oc.parameters[key].mandatorybooleanOptionalIf true, parameter is required (default: false)
oc.parameters[key].descriptionstring🔧 RecommendedParameter description for documentation
oc.parameters[key].examplestring🔧 RecommendedExample value for documentation
oc.parameters[key].defaultanyOptionalDefault value when parameter not provided

Advanced Configuration

ParameterTypeRequiredDescription
oc.pluginsarrayOptionalRequired plugins (e.g., ["oc-plugin-hash"])

Validation and Best Practices

Package.json Validation

Before publishing, validate your package.json:

# Check for required fields
oc package ./my-component --dry-run

# Validate parameter definitions
oc preview http://localhost:3030/my-component?param=value

Common Validation Errors

ErrorCauseSolution
"Missing template compiler"No devDependencies for template typeAdd "oc-template-{type}-compiler": "version"
"Invalid parameter type"Unsupported parameter typeUse "string", "boolean", or "number" only
"Template file not found"Wrong template.src pathVerify file exists and path is correct
"Invalid component name"Name contains invalid charactersUse kebab-case, lowercase, no spaces

Naming Conventions

  • Component names: Use kebab-case (user-profile, not UserProfile)
  • Parameter names: Use camelCase (showAvatar, not show_avatar)
  • File names: Use kebab-case for consistency
  • Versions: Follow semantic versioning (major.minor.patch)

Performance Considerations

  • Dependencies: Only include runtime dependencies, keep bundle size minimal
  • Static assets: Organize in logical directories, use compression
  • Parameters: Define clear types for better validation and performance
  • Minification: Keep oc.minify: true for production components

Troubleshooting

Common Issues

Problem: Component won't build

# Check package.json syntax
npm run build
# Verify all required fields are present

Problem: Parameters not working

# Validate parameter definitions
oc preview http://localhost:3030/component?debug=true

Problem: Static assets not loading

# Verify static directories exist and are listed in oc.files.static
ls -la public/

Next Steps