Skip to main content

Installation

This page covers the minimum setup for using Cotomy and the page-based structure it assumes.

Download source code: Cotomy v2.0.5 ZIP | Cotomy v2.0.5 TAR.GZ

Goals​

  • Add Cotomy to your project
  • Define a page-level endpoint
  • Understand the one-page, one-entry model
  • Confirm a basic build or script load

Environment Assumptions​

Cotomy does not require a specific framework. A build step is optional (TypeScript projects usually use one). You can:

  • Use a bundler (webpack, Vite, etc.)
  • Or load prebuilt JS if your setup provides it
RequirementNotes
ES module supportRequired for import syntax
TypeScript (optional)Recommended for medium to large projects
Bundler (optional)Helps organize per-page entry files
Modern browsersCotomy targets modern browser environments

Each page HTML file should load only its corresponding entry bundle. Avoid loading multiple page bundles into the same document.

Steps​

1) Install with npm​

npm install cotomy

2) Create a page entry​

Cotomy works best when each page has its own entry file and endpoint. This keeps lifecycle boundaries explicit and avoids hidden cross-page coupling.

Example structure:

src/
	pages/
		users/
			index.ts
			index.html
		settings/
			index.ts
			index.html

3) Configure per-page endpoints​

Expose one endpoint per page and map it to the matching entry file. How you do this depends on your stack, but the intent is the same:

  • /users -> src/pages/users/index.ts
  • /settings -> src/pages/settings/index.ts

In server-rendered apps, this typically means a route that renders the HTML and loads the corresponding script bundle for that page.

Why one entry per page?​

This is a structural safety rule, not a technical limitation:

SPA ModelCotomy Model
Global app rootIndependent page modules
Virtual stateDOM = state
Single client appPage lifecycle

It keeps behavior isolated and helps avoid cross-page leaks.

4) Example webpack setup​

If you bundle per page with webpack, define a multi-entry config and output to a page-specific bundle name.

Bundling per page is recommended for larger apps, but not required. Smaller setups can load Cotomy with a single script.

// webpack.config.cjs
const path = require("path");

module.exports = {
	mode: "development",
	entry: {
		users: "./src/pages/users/index.ts",
		settings: "./src/pages/settings/index.ts",
	},
	output: {
		path: path.resolve(__dirname, "dist"),
		filename: "[name].bundle.js",
	},
	resolve: {
		extensions: [".ts", ".js"],
	},
	module: {
		rules: [
			{
				test: /\.ts$/,
				use: "ts-loader",
				exclude: /node_modules/,
			},
		],
	},
};

Then reference the page bundle in each HTML file:

<script src="/dist/users.bundle.js"></script>
<script src="/dist/settings.bundle.js"></script>

5) Example Vite setup (optional)​

If you prefer Vite, use a multi-page build config:

// vite.config.ts
import { defineConfig } from "vite";
import { resolve } from "path";

export default defineConfig({
	build: {
		rollupOptions: {
			input: {
				users: resolve(__dirname, "src/pages/users/index.html"),
				settings: resolve(__dirname, "src/pages/settings/index.html"),
			},
		},
	},
});

6) Import Cotomy​

import { CotomyElement } from "cotomy";

7) Create your first Cotomy element​

import { CotomyElement } from "cotomy";

new CotomyElement({
	html: `<div class="hello">Hello Cotomy</div>`,
	css: `[root].hello { color: green; font-weight: bold; }`,
}).appendTo(new CotomyElement(document.body));

8) Verify the page​

Open the page and confirm there are no console errors.

  • Add the Cotomy package dependency
  • Import Cotomy in your entry file
  • Render a minimal Cotomy element
  • Verify the page loads without errors

Next​

Next: First UI.