more docs

Author: ricardo-devis-agullo

website/docs/components/cli.md

@@ -46,12 +46,86 @@ $ oc <command> [options]
 
 Hint: Run -h with any command to show the help
 
-For a list of all the available commands, ype **oc** in your terminal
+For a list of all the available commands, type **oc** in your terminal
 
 ```sh
 $ oc
 ```
 
+## Common Workflows
+
+Here are the most frequently used command sequences for typical OpenComponents workflows:
+
+### Creating and Testing a New Component
+
+```bash
+# Create component
+oc init my-component
+
+# Navigate to component
+cd my-component
+
+# Start development server
+oc dev . 3030
+
+# Preview component (in another terminal)
+oc preview http://localhost:3030/my-component
+```
+
+### Publishing Workflow
+
+```bash
+# Add registry (one-time setup)
+oc registry add https://my-registry.com
+
+# Package and publish
+oc publish my-component --username=myuser --password=mypass
+
+# Or test before publishing
+oc publish my-component --dryRun
+```
+
+### Development and Debugging
+
+```bash
+# Start dev server with verbose output
+oc dev . 3030 --verbose
+
+# Clean node_modules from all components
+oc clean . --yes
+
+# Mock plugins for local development
+oc mock plugin hash "test-value"
+```
+
+## Most Frequently Used Commands
+
+### Essential Commands (Daily Use)
+- `oc init <name>` - Create new component
+- `oc dev . <port>` - Start development server
+- `oc preview <url>` - Preview component
+- `oc publish <path>` - Publish component
+
+### Setup Commands (One-time)
+- `oc registry add <url>` - Add registry
+- `oc registry ls` - List registries
+
+### Maintenance Commands (Occasional)
+- `oc clean <path>` - Clean dependencies
+- `oc package <path>` - Package component
+- `oc mock plugin <name> <value>` - Mock plugins
+
+## Quick Reference
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `init` | Create component | `oc init header` |
+| `dev` | Start dev server | `oc dev . 3030` |
+| `preview` | Test component | `oc preview http://localhost:3030/header` |
+| `publish` | Deploy component | `oc publish header/` |
+| `registry add` | Add registry | `oc registry add https://my-registry.com` |
+| `clean` | Remove node_modules | `oc clean . --yes` |
+
 ---
 
 ### clean
@@ -135,18 +209,18 @@ $ oc init <componentPath> [templateType]
 | Name            | Description                                              | Default                |
 | --------------- | -------------------------------------------------------- | ---------------------- |
 | `componentPath` | The relative path with a name of the component to create |
-| `templateType`  | The name of the published template module on npm         | oc-template-handlebars |
+| `templateType`  | The name of the published template module on npm         | oc-template-es6 |
 
 #### Example:
 
 ```sh
-$ oc init test-component oc-template-jade
+$ oc init test-component oc-template-es6
 ```
 
 or with using relative path:
 
 ```sh
-$ oc init components/test-component oc-template-jade
+$ oc init components/test-component oc-template-es6
 ```
 
 which will create `test-component` in `components` directory.

website/docs/components/client-side-operations.md

@@ -80,10 +80,13 @@ Configure the client by exposing settings before including the script:
 
 ### Default Templates Configuration
 
+Modern OpenComponents uses ES6 templates by default. Legacy template types are still supported for backwards compatibility:
+
 ```js
 [
+  // Legacy template types (supported for backwards compatibility)
   {
-    type: "oc-template-jade",
+    type: "oc-template-jade", // Legacy - use ES6 templates for new components
     externals: [
       {
         global: "jade",
@@ -103,6 +106,8 @@ Configure the client by exposing settings before including the script:
 ];
 ```
 
+**Note**: ES6 templates are the recommended default for new components and don't require external dependencies.
+
 ## API Methods
 
 ### oc.addStylesToHead(styles)
@@ -228,7 +233,7 @@ Render a component using compiled view information and data model.
 ```js
 oc.render(
   {
-    type: "handlebars",
+    type: "es6", // Modern ES6 template (recommended)
     src: "https://registry.com/component/template.js",
     key: "template-hash",
   },
@@ -791,7 +796,7 @@ Available settings:
 | `retryInterval`    | `number` (milliseconds) | Retry interval for when component rendering fails                                                                                                                                                                                             | 5000                                                                                                                                                                                                                                                                                                 |
 | `retryLimit`       | `number`                | Max number of retries when component rendering fails                                                                                                                                                                                          | 30                                                                                                                                                                                                                                                                                                   |
 | `retrySendNumber`  | `boolean`               | Appends an `__ocRetry=(number)` to a request to mark the retry number. This is a quite powerful feature that you can handle in the server-side logic in order to make your component even behave differently in case something is going wrong | true                                                                                                                                                                                                                                                                                                 |
-| `templates`        | `array`                 | The configuration needed for performing client-side rendering of specific template types.                                                                                                                                                     | `[{"type": "oc-template-jade","externals": [{"global": "jade","url": "https://unpkg.com/[email protected]/runtime.js"}]},{"type": "oc-template-handlebars","externals": [{"global": "Handlebars","url": "https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.0.6/handlebars.runtime.min.js"}]}]` |
+| `templates`        | `array`                 | The configuration needed for performing client-side rendering of legacy template types. ES6 templates (default) don't require configuration.                                                                                                 | `[{"type": "oc-template-jade","externals": [{"global": "jade","url": "https://unpkg.com/[email protected]/runtime.js"}]},{"type": "oc-template-handlebars","externals": [{"global": "Handlebars","url": "https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.0.6/handlebars.runtime.min.js"}]}]` |
 | `tag`              | `string`                | The html tag you want to use for your components in the page                                                                                                                                                                                  | `oc-component`                                                                                                                                                                                                                                                                                       |
 
 ## API

website/docs/components/getting-started.md

@@ -4,7 +4,18 @@ sidebar_position: 1
 
 # Getting Started
 
-## Component creation
+## Prerequisites
+
+Before creating your first component, ensure you have:
+
+- **Node.js** (version 20 or higher) - [Download here](https://nodejs.org/)
+- **npm** (comes with Node.js) - Basic familiarity with npm commands
+- **Basic JavaScript knowledge** - Understanding of functions, objects, and modules
+- **Command line familiarity** - Ability to navigate directories and run commands
+
+**New to OpenComponents?** Consider starting with our [Quick Start Tutorial](../quick-start-tutorial) for a complete step-by-step guide.
+
+## Component Creation
 
 To create a component you need to install oc with a command:
 
@@ -23,10 +34,10 @@ The above command will create the `hello-world` [directory](#component-structure
 It is also possible to set [template](#template) type during the initialisation as an additional init parameter:
 
 ```bash
-$ oc init hello-world oc-template-jade
+$ oc init hello-world oc-template-es6
 ```
 
-By default this parameter is set to `oc-template-handlebars`.
+By default this parameter is set to `oc-template-es6` (modern ES6 templates). Legacy templates like `oc-template-handlebars` are still supported for backwards compatibility.
 
 ## Component structure
 
@@ -85,7 +96,7 @@ The basic package file `package.json` looks as follows:
 
 ## Template
 
-The template represents view layer of the component. OC support `Handlebars`(via the `oc-template-handlebars`) and `Jade`(via the `oc-template-jade`) out of the box, but it come with a powerful template system to support components built with any javascript UI framework like `React`, `Angular`, `Vue`...|
+The template represents view layer of the component. OC supports modern `ES6` templates by default, along with `React`, `Vue`, `Svelte`, and other javascript UI frameworks. Legacy templates like `Handlebars` and `Jade` are still supported for backwards compatibility.
 
 Initialisation produces a basic hello-world example.
 
@@ -135,3 +146,99 @@ $ oc preview http://localhost:3030/hello-world
 ```
 
 That's it. As soon as you make changes on the component, you will be able to refresh this page and see how it looks.
+
+## When to Use Components
+
+OpenComponents are ideal for:
+
+- **Shared UI elements** across multiple applications (headers, footers, navigation)
+- **Team independence** where different teams own different parts of the UI
+- **Gradual migration** from monolithic to micro frontend architecture
+- **A/B testing** individual components without affecting the entire application
+- **Third-party integrations** that need to be embedded in multiple sites
+
+## Example Repositories
+
+Explore these example repositories to see OpenComponents in action:
+
+- [OpenComponents Templates](https://github.com/opencomponents/vite-templates) - Modern component templates
+- [Storage Adapters](https://github.com/opencomponents/storage-adapters) - Different storage solutions
+- [Browser Client](https://github.com/opencomponents/oc-client-browser) - Client-side integration examples
+
+## Troubleshooting Common Issues
+
+### Installation Problems
+
+**Problem**: Permission errors when installing globally
+
+```bash
+# Solution: Use sudo (macOS/Linux) or run as administrator (Windows)
+sudo npm install oc -g
+```
+
+**Problem**: `oc` command not found after installation
+
+```bash
+# Check if npm global bin is in your PATH
+npm config get prefix
+# Add {prefix}/bin to your PATH environment variable
+```
+
+### Component Creation Issues
+
+**Problem**: `oc init` fails with template errors
+
+```bash
+# Solution: Specify template explicitly (ES6 is default)
+oc init hello-world oc-template-es6
+```
+
+**Problem**: Component won't start with `oc dev`
+
+```bash
+# Solution: Install dependencies first
+cd hello-world
+npm install
+oc dev . 3030
+```
+
+### Development Server Issues
+
+**Problem**: Port already in use
+
+```bash
+# Solution: Use a different port
+oc dev . 3031
+```
+
+**Problem**: Component shows "Loading..." forever
+
+- Check browser console for JavaScript errors
+- Verify the registry URL is accessible
+- Ensure component syntax is valid
+
+### Template Compilation Errors
+
+**Problem**: Template syntax errors
+
+- For ES6 templates: Validate your template literal syntax and ensure the function returns valid HTML
+- For legacy Handlebars templates: Validate template syntax and check for missing variables in server.js
+- Check for missing variables in server.js
+
+**Problem**: Server.js runtime errors
+
+- Check the server.js syntax
+- Verify all required parameters are handled
+- Add error handling in your data function
+
+## Next Steps
+
+Once you've created your first component:
+
+1. **[Learn the CLI](cli)** - Master all available commands
+2. **[Understand package.json structure](package.json-structure)** - Configure your component properly
+3. **[Add server-side logic](the-server.js)** - Make your component dynamic
+4. **[Publish to a registry](publishing-to-a-registry)** - Share your component
+5. **[Explore client-side operations](client-side-operations)** - Advanced browser integration
+
+For a complete hands-on tutorial, see our [Quick Start Tutorial](../quick-start-tutorial).

website/docs/components/package.json-structure.md

@@ -15,13 +15,13 @@ The basic package file `package.json` looks as follows:
     "files": {
       "data": "server.js",
       "template": {
-        "src": "template.hbs",
-        "type": "oc-template-handlebars"
+        "src": "template.js",
+        "type": "oc-template-es6"
       }
     }
   },
   "devDependencies": {
-    "oc-template-handlebars-compiler": "6.0.8"
+    "oc-template-es6-compiler": "6.0.8"
   }
 }
 ```
@@ -42,7 +42,7 @@ The basic package file `package.json` looks as follows:
 | `oc.files.data`                  | `string`           | the model provider's filename, by default `server.js`                                                                                                                          |
 | `oc.files.template`              | `object`           | represents the data involved with template - view, template engine                                                                                                             |
 | `oc.files.template.src`          | `string`           | the view's filename, by default template.html                                                                                                                                  |
-| `oc.files.template.type`         | `string`           | the template engine's type, by default `handlebars`                                                                                                                            |
+| `oc.files.template.type`         | `string`           | the template engine's type, by default `es6` (modern JavaScript templates). Legacy options like `handlebars` are still supported for backwards compatibility                |
 | `oc.files.static`                | `array of strings` | An array of directories that contain static resources referenced from the component's markup                                                                                   |
 | `oc.minify`                      | `boolean`          | Default `true`, will minify static css and js files during publishing                                                                                                          |
 | `oc.parameters`                  | `object`           | Describes the component's api. Used to auto-generate documentation and get requests validation. Each `key` is the parameter name                                               |

website/docs/components/the-server.js.md

@@ -16,8 +16,10 @@ and we don't need to modify any other files.
 
 But when we want to provide some additional logic in our view:
 
-```html
-<div>hello {{name}}</div>
+```javascript
+export default function(model) {
+  return `<div>hello ${model.name}</div>`;
+}
 ```
 
 we have to modify our `server.js` (model provider).
@@ -160,14 +162,14 @@ First step is to prepare `package.json` file. It is necessary to add `static` pr
     "files": {
       "data": "server.js",
       "template": {
-        "src": "template.html",
-        "type": "oc-template-handlebars"
+        "src": "template.js",
+        "type": "oc-template-es6"
       },
       "static": ["public"]
     }
   },
   "devDependencies": {
-    "oc-template-handlebars-compiler": "6.0.8"
+    "oc-template-es6-compiler": "6.0.8"
   }
 }
 ```
@@ -178,8 +180,10 @@ It is an array of names of directories. In the above example the `public` direct
 
 We can add image to the component view template using `img` tag in which `src` attribute is bound to `img` viewModel property.
 
-```html
-<img src="{{path}}public/static_resource.png" />
+```javascript
+export default function(model) {
+  return `<img src="${model.path}public/static_resource.png" />`;
+}
 ```
 
 ### Update server file