scittlets

[!NOTE] This project is in α. Features and APIs are unstable and subject to change.

Scittle brings the Small Clojure Interpreter to the browser, allowing you to run ClojureScript using simple <script> tags.

Overview

A scittlet is a Clojurescript namespace designed for use with Scittle, with a clearly defined set of <script> dependencies that can be loaded in any Scittle HTML file.

Scittlets is a versioned catalog and repository of these modules, providing examples and instructions for loading from CDN into your Scittle file. It also includes a command-line tool (scittlets) to help manage scittlet dependencies in HTML files.

The repository offers the scaffolding needed to develop, test, showcase, and publish scittlets, served via jsDelivr from the Scitlets GitHub project itself.

Usage

Explore available scittlets in the Web Catalog.

To use one:

• Add its listed dependencies to your Scittle HTML file manually, or
• Use the scittlets CLI command available via npx to manage dependencies easily.

Follow the usage instructions and demo code provided.

CLI: scittlets

Manage scittlet dependencies in HTML files.

Use the CLI with npx, no install required. Optional global install: npm install -g scittlets.

Run commands with:

npx scittlets <command> [options]

Commands

• new [template] [--directory path]

  Create a new app from the specified TEMPLATE. If no template is provided, lists available templates.

  Output directory defaults to the template's default directory but can be overridden with --directory (or -d).

• add <html> [scittlets..] [--list-scittlets]

  Add SCITTLETS dependencies to the target HTML file, or list them if none are provided.

  Use --list-scittlets (or -l) to list available scittlets from the catalog.

• update <html> [scittlets..]

  Update all scittlet dependencies in the HTML file at PATH using the latest catalog, or only those SCITTLETS if specified.

• pack <html> [target]

  Pack the HTML file by inlining <script src=""> elements directly into the file.

  Saves the output to target (default: packed.html).

• catalog [--release version]

  List all scittlets and templates in the catalog for the specified catalog release VERSION (default: latest).

• releases

  List all published release versions of the scittlets catalog.

Example usage

List available templates:

npx scittlets new

Create a new app with a specific template:

npx scittlets new reagent/codemirror

Add scittlet dependencies to HTML file:

npx scittlets add ./index.html scittlets.reagent.codemirror

List catalog release versions:

npx scittlets releases

List scittlets and templates for the latest release version:

npx scittlets catalog

Update all scittlets dependencies in an HTML file to their latest versions:

npx scittlets update ./index.html

Pack an HTML file and specify output filename:

npx scittlets pack ./index.html output.html

Important

• To avoid GitHub API rate limits, set the environment variable GITHUB_PUBLIC_TOKEN (no scopes needed):

  export GITHUB_PUBLIC_TOKEN=your_token_here
  # or, on PowerShell
  $env:GITHUB_PUBLIC_TOKEN="your_token_here"
  

Scittlets

scittlets.dev.nrepl

Provides dependencies and a babashka script for opening up an nREPL connection to the Scittle app.

scittlets.reagent

Provides dependencies for reagent, a simple ClojureScript interface to React.

scittlets.reagent.codemirror

A reagent component around CodeMirror, a code editor component for the web.

scittlets.reagent.mermaid

A reagent component around Mermaid, the diagramming and charting tool.

Development

Install dev dependencies:

$ npm install

Run the excellent cljs-josh live-reloading Scittle server:

$ npx josh
Serving ./ on port 8000:
- http://192.168.1.100:8000
- http://127.0.0.1:8000
SSE connection established

Scittlets are listed in catalog.json, the metadata registry.

Example Scittlet: scittlet.reagent.mermaid

Use this scittlet as a starting point for development:

• Code: src/scittlets/reagent/mermaid.cljs
• Metadata: catalog.json
• Card: test/scittlets/reagent/mermaid_card.cljs
• UI Test: test/scittlets/reagent/mermaid_test.cljs
• Test page: test/scittlets/reagent/mermaid.html
• Demo code: examples/mermaid/mermaid_demo.cljs
• Demo page: examples/mermaid/mermaid_demo.html

License

Licensed under the Eclipse Public License 1.0, same as Scittle. See LICENSE for details.