Developer Guide for Extending the zzson Web Tool
This guide is for developers who want to contribute to or extend the zzson
web tool. It covers the project structure, build process, and key development considerations.
Project Structure
The zzson
project uses a multi-crate Cargo workspace structure with Jekyll integration for web tools.
Workspace Structure
- Root: Multi-crate workspace with
Cargo.toml
defining members crates/core
: Core parsing functionality and AST typescrates/cli
: Command-line interface binarycrates/wasm
: WebAssembly bindings for browser usecrates/serde
: Serde integration for serialization supportcrates/test-utils
: Shared testing utilities
Web Tools Structure
docs/
: The root directory for the GitHub Pages site._config.yml
: Jekyll configuration file.tool.html
: ZZSON interactive tool (WebAssembly-powered)jsonic.html
: Jsonic interactive tool (CDN-powered)zzson-tool.md
: Jekyll wrapper for ZZSON tooljsonic-tool.md
: Jekyll wrapper for Jsonic tooltool.md
: Tools overview pageassets/
: Static assets for the web tools.css/
: CSS files, includingtool.css
andenhanced-features.css
.js/
: JavaScript files for both tools
pkg/
: Contains the compiled WebAssembly module (zzson_bg.wasm
,zzson.js
,zzson.d.ts
).
Development Environment Setup
To set up your development environment, you’ll need:
- Rust and Cargo: Follow the official Rust installation guide.
wasm-pack
: Install withcargo install wasm-pack
.- Node.js and npm: For managing JavaScript dependencies and running Jekyll.
- Ruby and Bundler: For Jekyll. Follow the Jekyll installation guide.
Build Process
- Build All Crates: Navigate to the project root and run:
./build.sh
This script handles formatting, linting, building, and testing all workspace crates.
- Build WebAssembly: For WASM specifically:
cd crates/wasm wasm-pack build --target web --out-dir ../../docs/pkg
- Build Jekyll Site: Navigate to the
docs/
directory and run:bundle install # First time setup bundle exec jekyll build
Or to serve locally for development:
bundle exec jekyll serve
The web tool will be accessible at
http://localhost:4000/tool.html
(or similar, depending on your Jekyll configuration).
Key Development Areas
Rust WebAssembly Bindings (src/wasm.rs
)
This file exposes Rust functions to JavaScript using #[wasm_bindgen]
. When adding new functionality from the Rust core to the web tool, you’ll modify this file.
#[wasm_bindgen]
: This macro handles the FFI (Foreign Function Interface) between Rust and JavaScript.- Error Handling: Rust
Result
types are automatically converted to JavaScript exceptions. Ensure your Rust code handles errors gracefully. - Data Conversion:
wasm_bindgen
handles conversion of basic types (strings, numbers, booleans, arrays, objects) between Rust and JavaScript. For complex types, you might need custom serialization/deserialization logic (e.g., usingserde
withwasm-bindgen-serde
).
JavaScript Logic (docs/assets/js/tool.js
)
This is the main JavaScript file for the web tool. It handles UI interactions, calls the WASM functions, and updates the display.
- WASM Module Import: The
pkg/zzson.js
module (generated bywasm-pack
) is imported here. - Asynchronous Operations: WASM module loading and initialization are asynchronous. Ensure you
await
theinit()
function. - UI Updates: Use standard DOM manipulation to update the input/output areas, error messages, and other UI elements.
- Event Listeners: Attach event listeners to buttons, toggles, and text areas to respond to user actions.
Examples (docs/assets/js/examples.js
)
This file contains the data for the pre-loaded examples. To add new examples:
- Define a new object in the
EXAMPLES
array withcategory
,name
,input
, andoptions
(if custom parser options are needed). - Ensure the
category
is consistent with existing categories or add a new one if appropriate.
Styling (docs/assets/css/tool.css
, enhanced-features.css
)
These CSS files define the visual appearance of the web tool. tool.css
contains core styles, while enhanced-features.css
handles specific styling for features like error highlighting.
Jekyll Integration
The web tool is part of a Jekyll static site. Key considerations:
- Front Matter: Each Markdown or HTML page uses YAML front matter to define layout, title, and navigation order.
- Includes: Jekyll allows reusing content snippets via
_includes/
. - Static Files: Ensure all assets (JS, CSS, WASM files) are correctly placed and referenced so Jekyll copies them to the
_site
directory.
Testing
After making changes, always:
- Rebuild WASM: Run
./build-wasm.sh
. - Rebuild/Serve Jekyll: Run
bundle exec jekyll build
orbundle exec jekyll serve
. - Test in Browser: Open the
tool.html
page in your browser and thoroughly test all functionalities, especially those you’ve modified.
Contributing
We welcome contributions! Please refer to the main Contributing Guide for general contribution guidelines, including how to submit pull requests and code style conventions.