docs

CrootJS Coding Conventions

These rules are mandatory for any code built with CrootJS — whether written by hand or generated by an AI coding agent (Claude Code, Cursor, Copilot, etc). They apply to CrootJS’s own repos (lib, docs, examples, crootjs.github.io) and to any project that imports CrootJS.

1. Separate HTML, CSS, and JS into their own files

• No inline <style> blocks in HTML. CSS lives in its own .css file, linked with <link rel="stylesheet" href="...">.
• No inline <script> blocks with logic in HTML. JS lives in its own .js file.
• No inline style="..." attributes. Use a class name and define the rule in the CSS file.
• No inline event handler attributes (onclick="...", onchange="...", oninput="...", etc). Attach listeners in JS with addEventListener (or CrootJS’s onClick/onChange/onInput helpers from element.js).

A page should look like this:

<!-- index.html -->
<link rel="stylesheet" href="style.css">
...
<button class="copy-btn">Copy</button>
...
<script type="module" src="script.js"></script>

// script.js
document.querySelectorAll('.copy-btn').forEach(btn => {
    btn.addEventListener('click', () => { /* ... */ });
});

Not like this:

<!-- don't -->
<style> .copy-btn { ... } </style>
<button style="color: blue" onclick="doThing()">Copy</button>
<script> function doThing() { ... } </script>

One exception: loading a third-party library from its own CDN (e.g. Lucide icons, SweetAlert2) via a plain <script src="..."> tag is fine — that’s an external dependency, not inline application logic.

2. JavaScript must be loaded as an ES module

Every .js file your page owns must be loaded with type="module":

<script type="module" src="script.js"></script>

Never as a plain classic script. This matches how CrootJS itself is distributed (import { x } from "https://cdn.jsdelivr.net/gh/crootjs/lib@<version>/module.js") and keeps the whole page in strict-mode ES module scope — no accidental globals.

3. Import CrootJS from a pinned CDN version

import { getJSON, postJSON } from "https://cdn.jsdelivr.net/gh/crootjs/lib@0.0.13/api.js";

• Always pin an exact version tag (@0.0.5), never @latest, in committed code — @latest can silently change behavior under you.
• Import only the specific module files you actually use (cookie.js, url.js, …), not the whole library, so the page only loads what it needs.

Why

• Maintainable: a reviewer (human or AI) can look at one file at a time instead of untangling markup, styling, and behavior mashed together.
• Cacheable: separate .css/.js files are cached by the browser independently of the HTML that changes more often.
• No build step required: this works with plain <link>/<script type="module"> tags — no bundler needed, consistent with CrootJS’s zero-install philosophy.
• AI-agent friendly: a coding agent generating or editing a CrootJS page has one unambiguous place to put each kind of code, instead of guessing whether to inline it.

For AI coding agents

If you (an AI agent) are building or editing a page that uses CrootJS, drop CLAUDE.md into the project root — Claude Code (and compatible agents that read a root instructions file) will pick these rules up automatically:

curl -o CLAUDE.md https://raw.githubusercontent.com/crootjs/lib/main/CLAUDE.md

Read it in a browser at croot.js.org/lib/CLAUDE.

This site is open source. Improve this page.