Skip to main content

Getting Started

Introduction guide — ← Back to Concept | Reference | Comparison

This guide is a short, practical entry point to Cotomy. Each page builds on the previous one.

Cotomy's Design Model​

Cotomy is a DOM-first UI runtime, not a global application framework. The basic unit is the page, and each page should:

  • Have its own entry file
  • Control only its own DOM
  • Avoid hidden cross-page dependencies

Note on sharing one entry file across multiple endpoints

The default model is one entry file per page. This keeps lifecycle boundaries explicit and avoids cross-page side effects.

If you intentionally choose to use a single entry file that handles multiple pages, treat it as an advanced configuration.

When using a shared entry file, you must enforce the same isolation rules in your own architecture:

  • Do not keep page-specific state in global variables or singletons
  • Do not retain DOM references across page navigations
  • Load page-specific logic conditionally based on URL or DOM context
  • Avoid retaining page-specific state after navigation (treat navigation as disposal)

In this setup, lifecycle safety depends more on your app design.

This model keeps behavior easier to trace in server-rendered or mixed environments. Cotomy avoids a global app container and virtual DOM layer; the DOM remains the UI state.

Cotomy scales by composing page modules instead of expanding a single client shell:

  • Each page has a bounded lifecycle
  • Memory and event handlers are naturally released on navigation
  • No single global state container grows over time
  • Server-rendered and SPA-style pages can coexist

If your team prefers:

  • Direct DOM control
  • Minimal runtime abstraction
  • Clear lifecycle boundaries
  • Compatibility with server-rendered systems

Cotomy generally fits well.

Cotomy is especially effective for systems where:

  • Pages are served independently
  • Business flows are document-driven
  • Server and client responsibilities are clearly separated

Instead of building a large, always-on client application, you build a set of predictable page modules.

How to Use This Guide​

  1. Start with Installation.
  2. Build a minimal UI with CotomyElement.
  3. Learn event handling, the DOM-state model, and forms.

Smallest Useful Mental Model​

For ordinary GET or POST navigation, start with a native HTML form:

<form action="/items" method="post">
  <input name="code" />
  <button type="submit">Save</button>
</form>

No CotomyForm is required when browser submission and page navigation are the desired behavior. Use CotomyForm or one of its subclasses only when Cotomy must intercept and control submission, such as GET query handling or API/Ajax submission.

Architecture Map​

Sections​

Next​

Use the Reference pages for detailed class and method descriptions.