iles: A Static Site Generator Where Only the Interactive Parts Ship JavaScript

Static Pages With Islands of Interactivity

iles takes its name from the French word for islands, and that word describes the whole architecture. A page is rendered to static HTML at build time, and the interactive parts of it are separate components that hydrate on the client. The README's feature list puts it first and states the rule plainly: zero JS by default, hydrates the interactive bits.

That is a different bargain from a single page application. The static parts of the page are HTML that arrives complete, and the JavaScript that hydrates an island is loaded only for the islands that need it. The result is a site that behaves like a document until a component decides otherwise.

The rest of the feature list shows how much the project tries to include. Batteries Included covers layouts, components and site-wide data. Multi-Framework means Vue, Preact, Svelte and Solid are all supported. Markdown can use components and components can use Markdown. Routing is configured automatically from files. There is a devtools debug panel and a hydration timeline. And development is powered by Vite, with instant reloading.

The project describes itself as a joyful site generator, and it is written in TypeScript, distributed on npm as iles, and licensed under MIT.

Partial Hydration Is a Per-Component Decision

Partial hydration is the one idea everything else follows from, and it deserves more attention than a bullet in a feature list, because it changes how a page is built.

In a conventional client-rendered framework, the whole page is a component tree and the JavaScript bundle boots the application. In a static site generator that ships no JavaScript by default, there is none unless you add it. In a partial hydration model, the choice is made per component, so a page can carry a static paragraph, a static illustration, and one interactive widget, and only the widget ships script.

The README credits Astro for sharing a novel way to define islands, and VitePress and vite-ssg for their different ideas on SSR, which places îles in a family of tools that all answer the same question differently rather than inventing the idea. The documentation site has a dedicated partial hydration guide, and the devtools include a hydration timeline, which is the debugging tool for exactly this: seeing when each island hydrates relative to the rest of the page.

For an evaluation, the practical question is whether your interactivity is concentrated in a few components. If it is, this model fits well. If most of your page is interactive, the island model stops being an advantage and starts being a constraint.

Four Frameworks in One Site

The Multi-Framework support is unusual among static site generators, and it is a deliberate design decision rather than an accident of the component model.

A component in an island is a self-contained unit, and if each island is compiled by the same toolchain, there is no reason for the islands to share a framework. So a page can mix a Vue island, a Solid island and a plain HTML island, and each one is hydrated independently with only its own framework runtime arriving. The feature list names Vue, Preact, Svelte and Solid, and the documentation has a Multi-Framework guide.

The practical value is for teams where the framework choice is not settled, or where a widget comes from a dependency written in a different framework than the rest of the site. The cost is bundle weight in a mixed site, because each distinct framework in use brings its own runtime for the islands that need it, and because you need to hold several mental models of reactivity while debugging.

The acknowledgements section also lists the components that carry the implementation: vue-router, @unhead/vue and vite-plugin-pages are described as the backbone of the library, and unplugin-vue-components is credited with letting you avoid boilerplate.

File Based Routing, Layouts and Site-wide Data

Batteries Included is the feature name for the things a static site generator is expected to handle and often leaves you to assemble: layouts, components and site-wide data.

Routing is automatic and derived from files, and vite-plugin-pages is listed among the library's backbone. The consequence is that the route table is a side effect of the directory structure, so moving a file moves a route, and the number of places you can get a URL wrong is small.

Layouts are the site-wide shell, and site-wide data is the shared content that pages can read, which in a static generator usually comes from the content files themselves. The documentation links to a searchable configuration reference alongside the guides, which suggests the configuration surface is large enough to need one.

Markdown is treated as a first-class format rather than an afterthought, and the feature is phrased in both directions: use components in Markdown, and vice versa. The MDX project is credited in the acknowledgements for providing flexibility when processing Markdown, and the guide for it is in the documentation. A blog that wants an interactive chart inside a post, or a docs site that wants a component-driven landing page, is what that combination is for.

The Vite Toolchain, Devtools and the Monorepo Behind It

The development experience is Vite, and the README lists Fast as a feature with the Vite link, describing it as instant reloading powered by Vite. Vite and Vue are acknowledged first among the credits, for the development experience, so the toolchain is a deliberate foundation rather than a wrapper.

The devtools are the part worth noticing, because a hydration model is only as good as your ability to see it working. The README points at a devtools debug panel and a hydration timeline image, and both exist because in a partially hydrated page, guessing is expensive. You need to know which islands hydrated, when, and whether an island that should have been interactive was left as static HTML.

The repository is a pnpm workspace with the package manager pinned at [email protected]. The root has packages/ for the workspace packages, playground/ for the demo projects, docs/ for the documentation site, scripts/ for tooling, an iles.config.ts for configuration, a netlify.toml for deployment, a Procfile.dev for development processes, and nx.json for task orchestration. The root scripts give the shape of the workflow: build:all and lint:all run tasks across the workspace with nx, release and changelog are TypeScript scripts under scripts/, pkg-size measures package size, and the test command runs packages/iles/bin/iles.js test.

Starting a Project and the Build Script

Creating a project is one command, and the same generator is available through the other package managers:

pnpm create iles@next # or npm or yarn

The @next tag in the create command is worth noticing, since the project publishes no GitHub releases and the versioning is handled through the npm package. The @next dist-tag means the generated project starts on the pre-release line, which for a project without tagged releases is the fastest way to get the current version of the tool.

Once a project exists, the documentation is the place to go next. The README points to the guides, to a searchable configuration reference, and to the configuration reference specifically for the settings that a site will need to change, while the routing and markdown guides cover the two conventions that differ most from other generators. There is also a StackBlitz link to fork the project and edit a Vue component in the browser, which is the fastest way to see the component model working before committing to it.

The project also runs a blog, the Vue Point with îles, and a documentation website, both of which are the reference implementations for how a real site is structured with the tool.

Where the Model Does Not Fit

The limitations follow from the same place the strengths do.

The first is that partial hydration is the wrong tool for an application. If most of a page needs client-side behaviour, islands fragment the state management, the page loads several framework runtimes, and the static HTML you shipped is thrown away quickly. A single page application with a real router and a data layer is a better fit for that shape of product, and the acknowledgements section names vite-ssg and VitePress as sources of the different SSR ideas that the project drew on rather than as a comparison.

The second is the release channel. There are no GitHub releases, and the last push was on 2026-04-10, which is more than six months before the present day. The repository is not archived, so it is not dead, but a project that ships through npm dist-tags rather than tagged releases gives you less to pin and less history to read. If you need a stable, dated version to depend on, check which npm dist-tag you are actually installing and record it.

The third is documentation density. The README is a feature list and a set of links, and the real content lives on the documentation site. That is a normal arrangement for a tool of this size, but it means evaluating it properly means reading the partial hydration and configuration pages rather than the README.

Editorial conclusion

iles fits a documentation site, a blog or a landing page that needs a few interactive widgets inside otherwise static prose, and it does not fit a highly dynamic application where most of the page is interactive, since the partial hydration model is built to keep JavaScript off the critical path rather than to maximise client-side behaviour. Before adopting it, read the partial hydration guide and the configuration reference, since the hydration strategy is a per-component decision rather than a project-wide switch, and check the routing and Markdown behaviour, because automatic routing from files and components inside Markdown are the two places where the conventions differ from a plain static site generator. The project is MIT licensed, published on npm as iles, publishes no GitHub releases, and the last push was on 2026-04-10.

Frequently asked questions

Official sources

1. ElMassimo/iles on GitHub
2. Issues
3. License: MIT
4. Project website
5. README