CWCO logo

v1.7.9

Getting Started

CWCO is just a fun tool to explore and for this guide, you will learn to setup your playground or project so you can start to play with it.

Know that CWCO was created with typescript and should be compatible already with any typescript project.

Experiment in Playgrounds

If you want to start right away, consider these browser ready editors playground:

  1. Examples Playground
  2. Static Site CodePen Playground
  3. Static Site StackBlitz Playground

These will allow you to explore CWCO right away in the browser in an interactive way.

Browser

If you have your project already you can go ahead and include the minified CWCO script link in the head of your page and start exploring it with your setup.

It's okay to add it to the header. It is a very small package.

<!-- index.html -->
<!doctype html>
<html lang="en">
<head>
	...
	
	<!-- import CWCO latest version -->
	<script src="https://unpkg.com/cwco/dist/cwco.min.js"></script>

</head>
<body>
  <!-- app content here -->
	<my-app>
		{title}
	</my-app>
	
  <!-- Always load your app script last -->
	<script src="my-app.js"></script>
</body>
</html>
 
// my-app.js

const {ContextProviderComponent} = window;

class MyApp extends ContextProviderComponent {
	title = "Hello World";
}

// register your app before any component
MyApp.register();

Node

To play with it in a Node environment, you must first install the package...

npm install cwco

...and then import it where you want.

const {
	WebComponent,
	ContextProviderComponent,
	Directive
} = require('cwco');

If you plan on running it on the server, you must include the window file before you import the CWCO package.

// add it before importing CWCO classes
// if you plan to execute the node file
import 'cwco/dist/node-window';

This file sets up some global objects like window, document, HTMLElement and customElements that the library relies on in order to run execute the component in a Node environment.

// add it before importing CWCO classes if you plan to execute execute the node file
import 'cwco/dist/node-window';
import {
	WebComponent,
	ContextProviderComponent,
	Directive
} from 'cwco';

The above setup will allow you to work just like you would in the browser.

// btn.js

// not needed if this code will run in the browser
require('cwco/dist/node-window');

const { WebComponent } = require('cwco');

class MyButton extends WebComponent {
	static observedAttributes = [
		'type',
		'label'
	];
	
	get template() {
		return `
			<button type="{type}">
				<slot>{label}</slot>
			</button>`;
	}
}

MyButton.register();

const btn = new MyButton();
btn.innerHTML = 'label'

document.body.appendChild(btn);

console.log(btn.root.innerHTML);
// run with 'node btn.js' to see result

If you are using a Node environment to code your project, but you will compile or build it before you run it in the browser, you DON'T need to import the window file.

Create a Project

CWCO does not need to be built or compiled, so it fits just fine with any project setup.

You can use CWCO with any project alongside any library or framework.

Vite project

npm init vite@latest
# follow the prompt (Pick vanilla project)

npm run dev # start project in the browser

Open the main.js file and drop this code to try things.

// main.js
import { WebComponent } from 'cwco';

class MyButton extends WebComponent {
	static observedAttributes = ['type', 'label'];
	
	get template() {
		return `
			<button type="{type}">
				<slot>{label}</slot>
			</button>`;
	}
}

MyButton.register();

Simply import cwco and start using it like normal.

<!-- documentation.html -->
<!DOCTYPE html>
<html lang="en">
<head>
	...
</head>
<body>
	
	<!-- build your view right in the HTML file -->
	<my-button type="button" onclick="alert('it works!')">
		click me
	</my-button>
	
	<script type="module" src="/main.js"></script>
	
</body>
</html>

Vite is an excellent tool to spin up quick projects, and you can use it to spin up other projects which cwco works fine with.

React + CWCO project

You can use create-react-app to spin a React app and create web component to use it there also.

npx create-react-app my-app
cd my-app
npm start

Create your component in a separate file (optional)...

// ./wc/MyButton
import { WebComponent } from 'cwco';

export class MyButton extends WebComponent {
	static observedAttributes = [
		'type',
		'label'
	];
	
	get template() {
		return `
			<button type="{type}">
				<slot>{label}</slot>
			</button>`;
	}
}

Import and register all your components before you render your React app.

// index.jsx
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

// import and use like a normal package
import { WebComponent } from 'cwco';
import { MyButton } from './wc/MyButton';

// register all web components
// before app is added to the DOM
WebComponent.registerAll([
	MyButton
]);

ReactDOM.render(
	<React.StrictMode>
		<App></App>
	</React.StrictMode>,
	document.getElementById('root')
);

Then you can use your components like any normal HTML tag.

// App.jsx
import logo from './logo.svg';
import './App.css';

function App() {
	const handleClick = () => {
		alert('it works!')
	};
	
	return (
		<div id="app">
			<header classname="App-header">
				...
			</header>
			<main>
				<my-button
					type="button"
					onClick={handleClick}
					label="Print Msg">
			</main>
		</div>
	);
}

export default App;

Angular + CWCO project

Angular projects can also use CWCO to build web components with few configurations.

Create your angular project with the following commands

# install angular CLI globally
npm install -g @angular/cli

# create your app
ng new my-app

# navigate inside your app
cd my-app

#install cwco
npm install cwco

#run your app
ng serve --open

Now go ahead and create your CWCO components, for example:

// src/app/web-components/my-button.component.ts
import { WebComponent } from 'cwco';

export class MyButton extends WebComponent {
	static override observedAttributes = [
		'type',
		'label'
	];
	
	override get template() {
		return `
			<button type="{type}">
				<slot>{label}</slot>
			</button>`;
	}
}

Add it to your application module

// src/app/app.module.ts

import {CUSTOM_ELEMENTS_SCHEMA, NgModule} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';
import {AppComponent} from './app.component';

// import 'WebComponent' from cwco module
// and all your components here
import {WebComponent} from 'cwco';
import {MyButton} from './web-components/my-button.component';

@NgModule({
	declarations: [
		AppComponent
	],
	imports: [
		BrowserModule
	],
	providers: [],
	bootstrap: [AppComponent],
	// needed to avoid unrecognized tag name errors
	schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {

	constructor() {
		// register all CWCO components
		WebComponent.registerAll([
			MyButton
		])
	}
}

After that you can start using your component as normal

<!-- src/app/app.component.html -->
<my-button type="button" onclick="alert('it works!')">
	click me
</my-button>

These are examples of few setups but using CWCO in a project is as simple as importing it and start using. There are no configurations or setup steps required by CWCO to start working with anything.

< Why CWCO? Creating Component >