Publishing to a registry
Publishing components to an OpenComponents registry makes them available for consumption across your applications. This guide covers the complete publishing workflow, from basic commands to advanced scenarios and troubleshooting.
Overview
Publishing is the process of uploading your packaged component to a registry where it becomes available for consumption. When you publish a component:
- Packaging: Your component is compiled and packaged with all dependencies
- Validation: The registry validates the component structure, CLI version, and custom rules
- Storage: The component is stored in the registry's storage backend
- Availability: The component becomes accessible via HTTP endpoints
Prerequisites
Publishing assumes:
- A reachable registry (see Registry Configuration)
- A component folder that passes
oc dev
validation - OC CLI installed (see CLI install)
That's all you need—no extra global setup.
Basic Publishing Workflow
1. Add Registry
First, configure your registry (only needed once):
oc registry add https://your-registry-domain.com
2. Publish Component
Navigate to your component directory and publish:
oc publish my-component/
This command will:
- Package your component automatically
- Compress it for upload
- Upload to all configured registries
- Make it available at
https://your-registry-domain.com/my-component
Authentication
Interactive Authentication
If the registry requires authentication, you'll be prompted for credentials:
oc publish my-component/
# Registry requires authentication
# Username: your-username
# Password: [hidden input]
Command-line Authentication
Provide credentials directly via command-line options:
oc publish my-component/ --username=your-username --password=your-password
Custom Authentication
Registries can implement custom authentication strategies. Check with your registry administrator for specific requirements.
CLI Options
The oc publish
command supports several options:
Option | Type | Description | Example |
---|---|---|---|
--username | string | Username for registry authentication | --username=john |
--password | string | Password for registry authentication | --password=secret |
--registries | array | Specific registries to publish to (overrides config) | --registries=http://reg1.com,http://reg2.com |
--skipPackage | boolean | Skip packaging step (use existing _package folder) | --skipPackage |
--dryRun | boolean | Test publish without actually uploading | --dryRun |
Examples
Basic publish:
oc publish my-component/
Publish with credentials:
oc publish my-component/ --username=developer --password=mypassword
Dry run (test without publishing):
oc publish my-component/ --dryRun
Publish to specific registries:
oc publish my-component/ --registries=https://staging-registry.com,https://prod-registry.com
Skip packaging (use pre-built component):
oc publish my-component/ --skipPackage
Advanced Usage
Multiple Registries
You can publish to multiple registries simultaneously:
# Configure multiple registries
oc registry add https://staging-registry.com
oc registry add https://production-registry.com
# Publish to all configured registries
oc publish my-component/
# Or specify registries for this publish only
oc publish my-component/ --registries=https://staging-registry.com
Pre-built Components
If you have a pre-packaged component in the _package
folder:
oc publish my-component/ --skipPackage
This skips the packaging step and directly publishes the existing package.
Testing with Dry Run
Always test your publish with --dryRun
first:
oc publish my-component/ --dryRun
This validates your component and simulates the publish process without actually uploading.
Version Management
- Component versions are determined by the
version
field inpackage.json
- You cannot publish the same name and version twice to the same registry
- Update your component version before publishing updates:
{
"name": "my-component",
"version": "1.0.1",
"oc": {
// component configuration
}
}
Troubleshooting
For error messages and advanced diagnostics, refer to the CLI Troubleshooting Guide. It covers authentication, versioning, validation failures, and more.
Debugging Tips
- Use dry run first: Always test with
--dryRun
before actual publishing - Check component structure: Ensure all required files are present
- Validate package.json: Verify the
oc
configuration is correct - Test locally: Use
oc dev
to test your component locally before publishing - Check registry logs: Contact your registry administrator for server-side error details
Getting Help
If you encounter issues not covered here:
- Check the component structure with
oc dev
- Validate your
package.json
configuration - Test with
--dryRun
to identify issues before publishing - Contact your registry administrator for authentication or server issues
- Check the OpenComponents GitHub repository for known issues
Best Practices
- Always use dry run first: Test your publish with
--dryRun
- Version management: Follow semantic versioning for your components
- Test locally: Use
oc dev
to test components before publishing - Secure credentials: Never commit passwords to version control
- Registry selection: Use staging registries for testing, production for releases
- Component validation: Ensure your component works in isolation before publishing