ArgNote
A notebook-style JavaScript playground you start with one command. Write code and Markdown in the browser, bundled live, and saved to a local file.
- Developer tools
SpecSheet 008
- Role
- Sole developer
- Year
- 2022
- Language
- TypeScript
- Platform
- Web
- Stack
- TypeScript
- React
- Redux
- Monaco Editor
- esbuild-wasm
- Express
- Commander
- Lerna
The problem
Trying out JavaScript usually means setting up a project, a bundler and a place to keep notes.
ArgNote starts with npx argnote serve: code is bundled in the browser as you type, can import any npm package, and sits alongside Markdown documentation in a single file.
The system
7 components · 6 connections · 2 request flows
One command starts a local server that serves a browser notebook. Code is bundled in the browser and runs in a sandboxed iframe; cells are saved to a file on disk.
Play a request
- Service
- Data store
- Client
- External service
- Data / control flow
- The request
- Trust boundary
Select a component to see its role, the technology behind it and what it talks to — or play a request and watch it travel the system.
Arrow keys move between components, Home and End jump to the first and last. Enter or Space selects one; Escape clears. Plus and minus zoom, 0 fits the map.
Component reference7 components · 2 flows · as text
Components · in request order
- Service · layer 01CLI
- argnote serve [file] -p [port] opens a notebook file (default notebook.js on port 4005) and starts the local server.
- TechCommander, Node.js
- ToLocal API (starts server)
- InsideYour machine
- Service · layer 02Local API
- Serves the notebook UI and exposes GET and POST /cells to load and save the cells of the open file.
- TechExpress
- FromCLI (starts server); Notebook UI (GET / POST /cells)
- ToNotebook file (read / write)
- InsideYour machine
- Data store · layer 03Notebook file
- The cells live in a plain file on disk, created on first run if it does not exist.
- Technotebook.js
- FromLocal API (read / write)
- InsideYour machine
- Client · layer 03Notebook UI
- Code and Markdown cells in the browser, with a VS Code style editor.
- TechReact, Redux, Monaco Editor, TypeScript
- ToLocal API (GET / POST /cells); In-browser bundler (cell code)
- InsideBrowser
- Service · layer 04In-browser bundler
- Transpiles and bundles the cell code inside the browser, resolving npm imports on the fly.
- Techesbuild-wasm
- FromNotebook UI (cell code)
- Tounpkg (imports + wasm); Sandboxed preview (bundle via postMessage)
- InsideBrowser
- Client · layer 05Sandboxed preview
- Bundled code runs in an iframe with sandbox=allow-scripts and receives its code by postMessage.
- Techiframe sandbox
- FromIn-browser bundler (bundle via postMessage)
- InsideBrowser
- External service · layer 05unpkg
- Serves the esbuild WebAssembly binary and the npm packages a cell imports.
- Techunpkg.com
- FromIn-browser bundler (imports + wasm)
Request flows
Run a cell
The cell's code is bundled in the browser, pulling any npm imports from unpkg, then handed to the sandboxed iframe to execute.
- Step 1: Notebook UI
- Step 2: In-browser bundler
- Step 3: Sandboxed preview
Save the notebook
The UI posts the list of cells to the local API, which writes them to the notebook file.
- Step 1: Notebook UI
- Step 2: Local API
- Step 3: Notebook file
Trust boundaries
- Your machine — CLI, Local API, Notebook file
- Browser — Notebook UI, In-browser bundler, Sandboxed preview
Decisions & trade-offs
4 decisions
Bundle in the browser, not on a server
esbuild compiled to WebAssembly transpiles and bundles the code client-side, so there is no build step to run locally and no server to execute untrusted code.
Run user code in a sandboxed iframe
Bundled code is posted into an iframe with sandbox=allow-scripts, isolated from the notebook UI.
Resolve npm imports through unpkg
Imports are fetched on demand, so any npm package can be used without installing it.
Ship as a multi-package CLI
The CLI, the local API and the UI are separate packages managed with Lerna and published to npm.
The write-up
This is an interactive coding environment. You can write Javascript, see it executed, and write comprehensive documentation using markdown.
Getting Started
To run this project run you can use npx
Shell1 line
npx argnote serveor install globally
Shell1 line
npm install --g argnoteand then run locally with
Shell1 line
argnote serveby which a default notebook file of notebook.js will be created and the default running port will be 4005.
You can change the file/directory and running port with
Shell1 line
argnote serve notebooks/test.js -p 5000by which the file test.js will be created into the directory notebooks. You will see your codes there.
To run the same file in the local server simply use the directory/filename you used.
Tech Stack
Client: React and Redux with TypeScript
Server: Node, Express
The whole project has been created with React 17 and written in TypeScript.
You can write codes in JavaScript and import any packages from npm.
VS Code users will feel at-home as the same code editor can be used to write the codes. The written codes will be compiled in real time as you code with a very high performance.
ESBuild WASM (web assembly) is used to bundle and transpile the codes directly into the browser. This is a task normally done by running Webpack and Babel at the terminal. The users' code is complied safely in the browser just like how famous services like CodeSandBox and CodePen do.The project is deployed using a multi-package architecture (Lerna) into NPM.
Commander is used to create the CLI commands for serving the project.
Appendix
Any additional information goes here
Badges
Contributing
Contributions are always welcome!
