Skip to content

Commit 38f2f16

Browse files
reword intros, consolidate
1 parent 6cad211 commit 38f2f16

File tree

4 files changed

+51
-144
lines changed

4 files changed

+51
-144
lines changed

website/docs/components/cli.md

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@ sidebar_position: 2
44

55
# Command Line Tool
66

7+
## Prerequisites
8+
9+
- **Node.js** 20 or newer (verify with `node -v`)
10+
- **npm** (ships with Node) — ensure it’s on your `$PATH`
11+
- Network reachability to your component registry (VPN/proxy if corporate)
12+
13+
If these are satisfied you can install the CLI as shown below.
14+
715
## Install the cli
816

917
To install cli, you should type:
@@ -101,33 +109,47 @@ oc mock plugin hash "test-value"
101109
## Most Frequently Used Commands
102110

103111
### Essential Commands (Daily Use)
112+
104113
- `oc init <name>` - Create new component
105114
- `oc dev . <port>` - Start development server
106115
- `oc preview <url>` - Preview component
107116
- `oc publish <path>` - Publish component
108117

109118
### Setup Commands (One-time)
119+
110120
- `oc registry add <url>` - Add registry
111121
- `oc registry ls` - List registries
112122

113123
### Maintenance Commands (Occasional)
124+
114125
- `oc clean <path>` - Clean dependencies
115126
- `oc package <path>` - Package component
116127
- `oc mock plugin <name> <value>` - Mock plugins
117128

118129
## Quick Reference
119130

120-
| Command | Purpose | Example |
121-
|---------|---------|---------|
122-
| `init` | Create component | `oc init header` |
123-
| `dev` | Start dev server | `oc dev . 3030` |
124-
| `preview` | Test component | `oc preview http://localhost:3030/header` |
125-
| `publish` | Deploy component | `oc publish header/` |
126-
| `registry add` | Add registry | `oc registry add https://my-registry.com` |
127-
| `clean` | Remove node_modules | `oc clean . --yes` |
131+
| Command | Purpose | Example |
132+
| -------------- | ------------------- | ----------------------------------------- |
133+
| `init` | Create component | `oc init header` |
134+
| `dev` | Start dev server | `oc dev . 3030` |
135+
| `preview` | Test component | `oc preview http://localhost:3030/header` |
136+
| `publish` | Deploy component | `oc publish header/` |
137+
| `registry add` | Add registry | `oc registry add https://my-registry.com` |
138+
| `clean` | Remove node_modules | `oc clean . --yes` |
128139

129140
---
130141

142+
## Installation Troubleshooting
143+
144+
| Symptom | Fix |
145+
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
146+
| `EACCES` permission errors on macOS/Linux | Re-run with `sudo npm install -g oc` or configure a user-level npm prefix |
147+
| `oc: command not found` | Ensure npm global bin folder is in `$PATH` (`npm config get prefix` → add `prefix/bin`) |
148+
| Port already in use when running `oc dev` | Choose another port: `oc dev . 3031` |
149+
| Component stuck on "Loading…" | Check browser console, verify registry URL, review template syntax |
150+
151+
For additional issues search the [GitHub discussions](https://github.com/opencomponents/opencomponents/discussions) or open a new ticket.
152+
131153
### clean
132154

133155
Remove the node_modules directory from each component's subfolder
@@ -206,8 +228,8 @@ $ oc init <componentPath> [templateType]
206228

207229
#### Parameters:
208230

209-
| Name | Description | Default |
210-
| --------------- | -------------------------------------------------------- | ---------------------- |
231+
| Name | Description | Default |
232+
| --------------- | -------------------------------------------------------- | --------------- |
211233
| `componentPath` | The relative path with a name of the component to create |
212234
| `templateType` | The name of the published template module on npm | oc-template-es6 |
213235

website/docs/components/getting-started.md

Lines changed: 3 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,9 @@ sidebar_position: 1
66

77
## Prerequisites
88

9-
Before creating your first component, ensure you have:
9+
Before creating your first component, make sure your workstation meets the [CLI installation requirements](cli.md#installation). If you followed the **Quick-Start Tutorial** you can skip this.
1010

11-
- **Node.js** (version 20 or higher) - [Download here](https://nodejs.org/)
12-
- **npm** (comes with Node.js) - Basic familiarity with npm commands
13-
- **Basic JavaScript knowledge** - Understanding of functions, objects, and modules
14-
- **Command line familiarity** - Ability to navigate directories and run commands
15-
16-
**New to OpenComponents?** Consider starting with our [Quick Start Tutorial](../quick-start-tutorial) for a complete step-by-step guide.
17-
18-
## Component Creation
19-
20-
To create a component you need to install oc with a command:
21-
22-
```bash
23-
$ npm install oc -g
24-
```
25-
26-
The next step is to initialise a component:
11+
First create the component directory:
2712

2813
```bash
2914
$ oc init hello-world
@@ -167,69 +152,7 @@ Explore these example repositories to see OpenComponents in action:
167152

168153
## Troubleshooting Common Issues
169154

170-
### Installation Problems
171-
172-
**Problem**: Permission errors when installing globally
173-
174-
```bash
175-
# Solution: Use sudo (macOS/Linux) or run as administrator (Windows)
176-
sudo npm install oc -g
177-
```
178-
179-
**Problem**: `oc` command not found after installation
180-
181-
```bash
182-
# Check if npm global bin is in your PATH
183-
npm config get prefix
184-
# Add {prefix}/bin to your PATH environment variable
185-
```
186-
187-
### Component Creation Issues
188-
189-
**Problem**: `oc init` fails with template errors
190-
191-
```bash
192-
# Solution: Specify template explicitly (ES6 is default)
193-
oc init hello-world oc-template-es6
194-
```
195-
196-
**Problem**: Component won't start with `oc dev`
197-
198-
```bash
199-
# Solution: Install dependencies first
200-
cd hello-world
201-
npm install
202-
oc dev . 3030
203-
```
204-
205-
### Development Server Issues
206-
207-
**Problem**: Port already in use
208-
209-
```bash
210-
# Solution: Use a different port
211-
oc dev . 3031
212-
```
213-
214-
**Problem**: Component shows "Loading..." forever
215-
216-
- Check browser console for JavaScript errors
217-
- Verify the registry URL is accessible
218-
- Ensure component syntax is valid
219-
220-
### Template Compilation Errors
221-
222-
**Problem**: Template syntax errors
223-
224-
- For ES6 templates: Validate your template literal syntax and ensure the function returns valid HTML
225-
- For legacy Handlebars templates: Validate template syntax and check for missing variables in server.js
226-
- Check for missing variables in server.js
227-
228-
**Problem**: Server.js runtime errors
229-
230-
- Check the server.js syntax
231-
- Verify all required parameters are handled
232-
- Add error handling in your data function
155+
- For installation problems, component creation errors, or dev-server hiccups, refer to the in-depth [CLI guide](cli.md#troubleshooting) which contains up-to-date solutions.
233156

234157
## Next Steps
235158

website/docs/intro.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ sidebar_position: 1
66

77
OpenComponents is a framework for building and deploying **micro frontends** - small, independent, and reusable UI components that can be developed by different teams and composed into larger applications.
88

9+
## Target Audience
10+
11+
OpenComponents is built for **companies with multiple autonomous teams** that ship UI independently. If you’re a solo developer, this approach may be over-engineering.
12+
913
## What is OpenComponents?
1014

1115
Think of OpenComponents as a way to break down your frontend into small, manageable pieces that can be:
@@ -193,13 +197,9 @@ When retrieving multiple components, a [batch POST endpoint](/docs/consumers/bat
193197
- [Rails client](https://github.com/opencomponents/opencomponents-rails)
194198
- [Sinatra client](https://github.com/opencomponents/sinatra-opencomponents)
195199

196-
# Install the cli
200+
### Install the CLI
197201

198-
```sh
199-
npm install oc -g
200-
# to see available commands:
201-
oc
202-
```
202+
See the dedicated [CLI guide](components/cli#install-the-cli) for installation, shell-autocomplete, and update instructions.
203203

204204
# Setup a library
205205

website/docs/quick-start-tutorial.md

Lines changed: 10 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,7 @@ This comprehensive tutorial will guide you through creating your first OpenCompo
88

99
## Prerequisites
1010

11-
Before you begin, make sure you have:
12-
13-
- **Node.js** (version 20 or higher) - [Download here](https://nodejs.org/)
14-
- **npm** (comes with Node.js) - Basic familiarity with npm commands
15-
- **Basic JavaScript knowledge** - Understanding of functions, objects, and modules
16-
- **Command line familiarity** - Ability to navigate directories and run commands
17-
- **A cloud storage solution** such as:
18-
- [AWS S3](https://aws.amazon.com/s3)
19-
- [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
20-
- [Google Cloud Storage](https://cloud.google.com/storage)
11+
OpenComponents requires [Node.js](https://nodejs.org/) 20+ and the OC CLI. If the CLI isn’t installed yet, follow the [CLI installation guide](components/cli#install-the-cli) and then return here.
2112

2213
## What You'll Learn
2314

@@ -29,36 +20,7 @@ By the end of this tutorial, you'll know how to:
2920
- Publish components to a registry
3021
- Consume components in web applications
3122

32-
## Step 1: Install the OpenComponents CLI
33-
34-
First, install the OpenComponents command-line interface globally:
35-
36-
```bash
37-
npm install -g oc
38-
```
39-
40-
Verify the installation:
41-
42-
```bash
43-
oc --version
44-
```
45-
46-
You should see the version number displayed.
47-
48-
### Troubleshooting Installation
49-
50-
**Problem**: Permission errors on macOS/Linux
51-
52-
```bash
53-
sudo npm install -g oc
54-
```
55-
56-
**Problem**: `oc` command not found
57-
58-
- Make sure your npm global bin directory is in your PATH
59-
- Try: `npm config get prefix` and add `{prefix}/bin` to your PATH
60-
61-
## Step 2: Create Your First Component
23+
## Step 1: Create Your First Component
6224

6325
Let's create a simple "hello-world" component:
6426

@@ -102,7 +64,7 @@ oc init my-component --template-type=vue
10264
oc init my-component --template-type=svelte
10365
```
10466

105-
## Step 3: Explore Your Component
67+
## Step 2: Explore Your Component
10668

10769
Navigate to your component directory:
10870

@@ -129,7 +91,7 @@ export default function (model) {
12991
}
13092
```
13193

132-
## Step 4: Start Local Development
94+
## Step 3: Start Local Development
13395

13496
Start a local development registry:
13597

@@ -164,7 +126,7 @@ Or use the CLI preview:
164126
oc preview http://localhost:3030/hello-world
165127
```
166128

167-
## Step 5: Customize Your Component
129+
## Step 4: Customize Your Component
168130

169131
Let's modify the component to make it more interesting. Edit the `server.js` file:
170132

@@ -208,15 +170,15 @@ export default function (model) {
208170

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

211-
## Step 6: Test with Parameters
173+
## Step 5: Test with Parameters
212174

213175
Try your component with different parameters:
214176

215177
```
216178
http://localhost:3030/hello-world?name=Alice
217179
```
218180

219-
## Step 7: Create a Test HTML Page
181+
## Step 6: Create a Test HTML Page
220182

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

@@ -242,7 +204,7 @@ Create a simple HTML file to test client-side rendering:
242204

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

245-
## Step 8: Set Up a Registry (Production)
207+
## Step 7: Set Up a Registry (Production)
246208

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

@@ -294,7 +256,7 @@ registry.start((err, app) => {
294256
});
295257
```
296258

297-
## Step 9: Publish Your Component
259+
## Step 8: Publish Your Component
298260

299261
### Configure Registry
300262

@@ -321,7 +283,7 @@ Your component should now be available at:
321283
https://your-registry-domain.com/hello-world
322284
```
323285

324-
## Step 10: Consume in Production
286+
## Step 9: Consume in Production
325287

326288
Update your HTML to use the production registry:
327289

0 commit comments

Comments
 (0)