🏗️ Step 1: Create Your First Component​

mkdir oc-tutorial && cd oc-tutorial

hello-world/
├── 📄 package.json          # Component configuration & metadata
├── 📁 src/
│   ├── 🎨 view.ts           # TypeScript template (the UI)
│   └── ⚙️ server.ts         # Server-side logic & data
├── 📁 public/
│   └── 🖼️ logo.png          # Static assets (images, CSS, etc.)
├── ⚙️ tsconfig.json         # TypeScript configuration
└── 📦 node_modules/         # Dependencies

Template Options​

OpenComponents supports multiple template types:

• ES6 (default): Modern JavaScript with template literals - recommended for new components
• React: For React-based components with JSX
• Vue: For Vue.js single-file components
• Svelte: For Svelte components

You can specify the template type when creating a component:

oc init my-component --template-type=react
oc init my-component --template-type=vue
oc init my-component --template-type=svelte

Step 2: Explore Your Component​

Understanding Component Parameters​

The generated component includes parameters that you need to know about. Let's check what parameters are required:

cd hello-world
cat package.json

Look for the oc.parameters section in the package.json. You'll notice that some parameters may be marked as "mandatory": true. This is crucial for testing your component.

Examine the Generated Files​

Navigate to your component directory:

Look at the generated template:

You'll see something like:

export default function (model) {
  return `
    <div>
      <h1>Hello ${model.name}!</h1>
      <img src="${model.staticPath}/img/logo.png" alt="Logo" />
    </div>
  `;
}

Step 3: Start Local Development​

Important: Run the development server from the parent directory (not inside the component directory):

cd ..  # Go back to oc-tutorial directory

Start a local development registry:

This command:

• Starts a local registry on port 3030
• Watches for file changes
• Automatically recompiles your component

You should see output like:

Registry started at http://localhost:3030
Watching for changes...

Test Your Component​

Open your browser and visit:

• Component endpoint: http://localhost:3030/hello-world?userId=1
• Component info: http://localhost:3030/hello-world/1.0.0/~info

Important: The generated component requires parameters. If you get an error about "missing mandatory parameters", check the component info page to see what parameters are required.

Check Component Information​

Visit http://localhost:3030/hello-world/1.0.0/~info to see detailed information about your component, including all available parameters and which ones are mandatory.

Understanding Different Component URLs​

OpenComponents provides several ways to access your component:

1. JSON API (for programmatic access):

   http://localhost:3030/hello-world?userId=1
   

   Returns the component data as JSON

2. Component Info Page (for development/testing):

   http://localhost:3030/hello-world/1.0.0/~info
   

   Shows component details with live preview

3. Direct Preview (for embedding):

   http://localhost:3030/hello-world/1.0.0/~preview
   

   Shows just the rendered component

Or use the CLI preview:

oc preview http://localhost:3030/hello-world

Note: If the preview command doesn't work, don't worry - you can test your component directly in the browser using the URLs above.

Step 4: Test Interactive Features​

1. Visit http://localhost:3030/hello-world?userId=1
2. Click the "Fun year fact" button
3. You should see a fact about the birth year appear

Step 5: Customize Your Component​

Let's modify the component to make it more interesting. Edit the src/server.ts file:

import { Server } from "oc-server";

function getTimeBasedGreeting(): string {
  const hour = new Date().getHours();
  if (hour < 12) return "Good morning";
  if (hour < 18) return "Good afternoon";
  return "Good evening";
}

export const server = new Server()
  .withParameters({
    name: {
      type: "string",
      mandatory: false,
      default: "World",
      description: "Name to greet",
    },
  })
  .handler(async (params, ctx) => {
    const greeting = getTimeBasedGreeting();

    return {
      name: params.name ?? "World",
      greeting,
      staticPath: ctx.staticPath,
      timestamp: new Date().toISOString(),
    };
  });

Update the template (src/view.ts):

export default function (model: {
  name: string;
  greeting: string;
  staticPath: string;
  timestamp: string;
}) {
  return `
    <div style="padding: 20px; border: 1px solid #ddd; border-radius: 8px;">
      <h1>${model.greeting}, ${model.name}!</h1>
      <p>This component was rendered at: ${model.timestamp}</p>
      <img src="${model.staticPath}logo.png" alt="OpenComponents Logo" style="max-width: 100px;" />
    </div>
  `;
}

Save the files and refresh your browser - you should see the changes immediately!

Step 6: Test with Parameters​

Try your component with different parameters:

http://localhost:3030/hello-world?userId=0

Step 7: Create a Test HTML Page​

Create a simple HTML file to test client-side rendering:

<!DOCTYPE html>
<html>
  <head>
    <title>Testing My Component</title>
  </head>
  <body>
    <h1>My Website</h1>

    <!-- Your component will be rendered here -->
    <oc-component href="http://localhost:3030/hello-world?userId=1">
      Loading component...
    </oc-component>

    <!-- OpenComponents client script -->
    <script src="http://localhost:3030/oc-client/client.js"></script>
  </body>
</html>

Open this HTML file in your browser to see client-side rendering in action.

Step 8: Set Up a Registry (Production)​

For production use, you'll need a registry connected to cloud storage. Here's a basic setup:

Create Registry Directory​

mkdir my-oc-registry
cd my-oc-registry
npm init -y
npm install oc --save

Create Registry Configuration​

Create an index.js file:

const oc = require("oc");

const configuration = {
  verbosity: 0,
  baseUrl: "https://your-registry-domain.com/",
  port: 3000,
  tempDir: "./temp/",
  refreshInterval: 600,
  pollingInterval: 5,

  // For AWS S3
  s3: {
    key: process.env.AWS_ACCESS_KEY_ID,
    secret: process.env.AWS_SECRET_ACCESS_KEY,
    bucket: process.env.S3_BUCKET,
    region: process.env.AWS_REGION,
    path: `//s3.amazonaws.com/${process.env.S3_BUCKET}/`,
    componentsDir: "components",
  },

  env: { name: "production" },
};

const registry = oc.Registry(configuration);

registry.start((err, app) => {
  if (err) {
    console.log("Registry not started: ", err);
    process.exit(1);
  }
  console.log("Registry started successfully");
});

Step 9: Publish Your Component​

Configure Registry​

Add your registry to the CLI:

oc registry add https://your-registry-domain.com/

Publish​

Navigate back to your component directory and publish:

cd ../hello-world
oc publish . --username=your-username --password=your-password

Verify Publication​

Your component should now be available at:

https://your-registry-domain.com/hello-world

Step 10: Consume in Production​

Update your HTML to use the production registry:

<oc-component
  href="https://your-registry-domain.com/hello-world/1.X.X?name=Production"
>
  Loading component...
</oc-component>
<script src="https://your-registry-domain.com/oc-client/client.js"></script>

Common Troubleshooting​

Directory Issues​

Problem: "no components found in specified path" Solution: Make sure you're running oc dev . 3030 from the parent directory containing your components, not from inside the component directory.

Parameter Issues​

Problem: "Expected mandatory parameters are missing" Solution: Check the component info page at /~info to see what parameters are required, then include them in your URL.

General Issues​

Component Won't Start​

Problem: Error: Cannot find module Solution: Run npm install in your component directory

Problem: Port already in use Solution: Use a different port: oc dev . 3031

Publishing Issues​

Problem: Authentication failed Solution: Check your username/password and registry URL

Problem: Component already exists Solution: Update the version in package.json or use --force flag

Runtime Errors​

Problem: Component shows "Loading..." forever Solution:

• Check if you're including required parameters in the component URL
• Visit the component info page (/~info) to see parameter requirements
• Check browser console for errors
• Verify registry is accessible
• Check component syntax

Problem: Template compilation errors Solution:

• Validate your ES6 template syntax
• Check for missing variables in server.js
• Ensure template function returns valid HTML string

Performance Issues​

Problem: Slow component loading Solution:

• Optimize images and static assets
• Minimize server.js logic
• Use CDN for static resources

Next Steps​

Understanding Your Component​

The generated component demonstrates several OpenComponents features:

• Parameter Handling: Shows how to define and use mandatory/optional parameters
• Server Actions: The "funFact" button demonstrates client-server communication
• CSS Modules: Scoped styling that won't conflict with other components
• TypeScript: Type safety for better development experience
• Client-side Interactivity: Event handling within components

Now that you've created your first component, explore these advanced topics:

1. Component Structure - Learn about advanced component patterns
2. Server-side Logic - Add complex data processing
3. Client-side Operations - Advanced browser integration
4. Registry Configuration - Production registry setup
5. Template System - Use React, Vue, or other frameworks

Best Practices​

For Beginners​

• Always run oc dev from the directory containing your components, not from inside a component

• Check component info at /~info to see required parameters

• Use the browser console to debug client-side issues

• Test both client-side and server-side rendering to ensure compatibility

• Keep components small and focused - Each component should have a single responsibility

• Use semantic versioning - Follow semver for component versions

• Test thoroughly - Test both server-side and client-side rendering

• Optimize for performance - Minimize bundle size and dependencies

• Document your components - Include clear parameter descriptions

• Handle errors gracefully - Provide fallback content and error handling

Getting Help​

• Documentation: Continue reading the full documentation
• GitHub Issues: Report bugs or request features
• Community: Join discussions and get help from other developers

Congratulations! You've successfully created, developed, and published your first OpenComponents component. You're now ready to build scalable micro frontends with OpenComponents.