ierislab-utils

The goal of this project is to develop a small suite of privacy-respecting tools for use cases where a web-based interface is more appropriate than shell scripts or anything more complex. With all the logic running client-side only, it means there is no backend and no unnecessary eyes on the data.

Tech Stack

Astro handles static page generation and routing, with React islands for interactive tool UIs. SCSS provides structured styling and TypeScript covers all components and pages. This makes for a lean tech stack with great developer experience.

Development

Adding a Tool

1. Create src/pages/tools/<name>.astro
2. Export a meta object of type ToolMeta (from @definitions/tool)

The dashboard auto-discovers all files under src/pages/tools/ at build time. Tools without a valid meta export are still accessible by URL but won't appear in the dashboard.

React Components

React components are useful for stateful user interfaces. They exist under src/components/, and can be mounted with client:load in the tool's Astro page so the script loads for the client and not just at build time.

Static structure (headings, subtitles) stays in the Astro page; only the interactive part becomes a React island.

Path Aliases

Several aliases with a prefix @, are available for import: for example, @components/PasswordChecker. The full list is in tsconfig.json.

Styling

All styles are aggregated through a single entry point: src/styles/index.scss. Do not import SCSS files directly in pages or components — instead, add a partial and forward it from src/styles/index.scss (or the appropriate sub-index). This keeps the site to one stylesheet that can be cached by the browser rather than reloading on every page load.

Per-tool partials should scope styles under a short, unique class on the root element (e.g. .pwck for the password checker). Use SCSS nesting and element selectors inside that scope rather than adding classes to every element, additional classes are fine when nesting alone isn't sufficient.

Deployment

This is a fully static site. After running npm run build, the dist/ directory can be served by any static file server or hosting platform (Nginx, Caddy, etc.) with no server-side runtime required.

License

ierislab-utils is free software: you can redistribute it and/or modify it under the terms of the GPLv3. You can find a copy of the license text in the file called LICENSE at the root of this repository or online at gnu.org