Pluto.jl

Pluto uses the i18next library to manage UI translations via standard JSON files. Each language has its own JSON file in the frontend/lang/ directory.

Key Concepts

• Fallback: If a translation is missing in the selected language, Pluto falls back to English.
• Interpolation: Strings can include placeholders like {{variable}} (e.g., "Welcome to {{pluto_logo}}"). You must preserve the exact placeholder syntax in your translation, though you can change its position.
• Pluralization: To handle different plural forms, use the following suffixes on your keys:
  • _zero
  • _one
  • _two
  • _few
  • _many
  • _other

Example for pluralization:

"t_new_messages_zero": "You have no new messages 🥺",
"t_new_messages_one": "You have {{count}} new message",
"t_new_messages_other": "You have {{count}} new messages"

All third-party browser dependencies used by the Pluto frontend are wrapped in tiny ES-module files located in frontend/imports/. The rest of the frontend/ directory must import exclusively from this folder; direct CDN URLs should never appear elsewhere in the codebase.

Each dependency typically consists of two files:

• Foo.js: A wrapper that imports from a pinned CDN URL and re-exports the required surface. It uses // @ts-ignore or // @ts-nocheck on the CDN import line.
• Foo.d.ts: A type stub. This can be hand-written, a one-liner re-exporting from an npm package, or auto-generated.

Naming Convention for Collisions: If an npm package name collides with the wrapper filename (e.g., lodash), use the -es suffix for the wrapper to avoid TypeScript circular alias errors (TS2303).

• Example: lodash-es.js (wrapper) and lodash-es.d.ts (type stub).

Pluto notebooks are reactive environments composed of small Julia code cells.

• Reactivity: When you change a variable or function, Pluto automatically re-runs all cells that depend on it. Dependencies are determined via intelligent syntax analysis.
• File Format: Notebooks are saved as pure .jl Julia files. This allows you to import them into a regular editor as standard Julia code.
• Exporting: You can export notebooks as HTML or PDF documents, with the ability to hide code and reorder cells to control the narrative flow.

The Pluto Frontend Bundler uses Parcel and a custom resolver (parcel-resolver-like-a-browser) to crawl the Pluto application and bundle its dependencies. This allows for a compiled version of the frontend that can run without an internet connection.

To build the standard and offline distributions, follow these steps from the frontend-bundler directory:

cd frontend-bundler

npm install

rm -rf ../frontend/.parcel-cache
rm -rf ../frontend-dist
rm -rf ../frontend-dist-offline
npm run build
npm run build-offline

To install and run Pluto, start a Julia session and execute the following commands:

1. Import the Pluto package.
2. Run Pluto.run() to start the server.

For a complete guide on installing Julia and Pluto, visit plutojl.org/#install.

import Pluto
Pluto.run()

To add a new third-party dependency:

1. Create Foo.js in frontend/imports/. Import from a pinned CDN URL and re-export only the necessary surface (avoid export * to aid tree-shaking).
2. Add Foo.d.ts. For packages with existing types, use a stub like import * as Foo from "foo"; export default Foo; and add the package to frontend/package.json devDependencies.
3. Strict Import Rule: Only import Foo from ./imports/Foo.js within the frontend/ directory. Never use CDN URLs directly in other files.
4. Perform the type-check, dev smoke-test, and bundler build steps defined in the update guide.

Pluto automatically manages a dedicated package environment for every notebook using syntax analysis.

• Automatic Management: You can directly import any registered Julia package (e.g., Plots or DataFrames) without manual installation steps.
• Reproducibility: The exact package environment required to run the notebook is stored within the notebook file itself. When sharing a notebook, the recipient's Pluto instance will automatically use the correct package versions.

Pluto provides a @bind macro to create live connections between browser-based UI widgets and Julia variables. When a user interacts with a widget (like a slider), the bound Julia variable updates, triggering reactivity in all dependent cells.

For basic UI components like sliders and buttons, use the PlutoUI package.