🧚 Gracile

A thin, full-stack, web framework.

Features:

• Portable HTML, CSS and JS, thanks to Lit (SSR).
• Highly responsive during dev. and build, thanks to Vite.
• Minimal dependency footprint for its runtime and your distributable.
• Embrace web standards like Custom Elements (aka Web Components) or the WhatWG Fetch API.
• A streamlined Developer eXperience for building, instead of fiddling around.

🏁 Get Started

Bootstrap a project with the create gracile@latest command:

npm create gracile@latest
pnpm create gracile@latest
bun create gracile@latest
yarn create gracile@latest

For more information, head over to the documentation website (gracile.js.org).

🌐 A platform-minded meta-framework

Gracile is powered by Vite and Lit SSR.

With it, you can achieve:

• File-based routing with efficient code-splitting
• Server Side Rendering
• Static Site Generation
• Server integration (Request/Response) for Express, Hono…
• Full-stack Custom Elements (Lit), with hydration
• Content websites
• Multi or Single Page Applications
• Progressive enhancements (no JS fallbacks, smart hydration…)
• And more, via Add-ons (Markdown, Metadata, SVG…)

All that, with a few conventions, a standard-oriented approach and a very contained footprint 🤏.

Web Components, TypeScript, SASS, Lit, and other DX perks are all at your fingertips; while remaining optional.

Thanks to the Vite modular architecture, and Node.js versatility, developer experience is smoothed up across the board, while in development and when building for production.

Ease of use

Write the same markup, styling and scripting languages for both server and client side.
The ones that you already know and use everywhere else: HTML, CSS and JavaScript.

Simplicity doesn't mean obfuscation. You're still in charge without abandoning flexibility to your framework.

Standards oriented

Built with a platform-minded philosophy. Every time a standard can be leveraged for a task, it should be.
It also means fewer vendor-specific idioms to churn on and a more portable codebase overall.
Stop re-implementing the wheel, and embrace future-proof APIs, you'll thank yourself later!

Developer Experience

The DX bar has been constantly raised, alongside developers' expectations about their everyday tooling.
The "Vanilla" community is full of gems, in a scattered way.
Gracile provides an integrated, out-of-the-box experience while keeping non-core opinions as opt-ins.

Convention over configuration

Finding the right balance between convenience and freedom is tricky.
Hopefully, more and more patterns will be established in the full-stack JS space.

Gracile is inspired by those widespread practices that will make you feel at home.

Light and unobtrusive

All in all, the Gracile framework is just Vite, Lit SSR and a very restricted set of helpers and third parties.
Check its dependency tree on npmgraph, you'll see by yourself.
Also, everything is done to keep your Vite configuration as pristine as possible. Augmenting an existing project can be done in a pinch, with no interference.

Performances

Speed is not the main goal for Gracile, that's because it is just the sane default you'll start with.
Avoiding complex template transformations, or surgically shipping client-side JS are just a few facets of what makes Gracile a "do more with less" power tool.

Packages

Core

	Package	Description
	@gracile/gracile	Full-stack web framework — Vite & Lit SSR
	@gracile/engine	Vite-powered build and dev server engine
	@gracile/server	Server-side utilities and SSR helpers
	@gracile/client	Client-side utilities and interactive helpers
	@gracile/cli	CLI and configuration loader
	create-gracile	Project scaffolder (npm create gracile)

Add-ons

	Package	Description
	@gracile/markdown	Markdown file import with metadata extraction
	@gracile/markdown-preset-marked	Markdown preset using Marked
	@gracile/metadata	Page head metadata helper (title, OG…)
	@gracile/sitemap	Sitemap and robots.txt generation
	@gracile/svg	SVG import, optimization and inlining

Labs (@gracile-labs)

	Package	Description
	client-router	Client-side routing for Gracile pages
	islands	Islands architecture with multi-framework hydration
	hmr	Web Components HMR Vite plugin
	css-helpers	Adopted stylesheets utilities for web components
	better-errors	Enhanced error display and formatting
	functional	Signal-based hooks and context primitives
	devtools	In-browser dev panel for routes and state

Labs — JSX & Templates

	Package	Description
	jsx-forge	Native TS compiler: JSX to HTML template literals
	vite-plugin-jsx-forge	Vite plugin for JSX Forge
	babel-plugin-jsx-to-literals	Babel plugin: JSX to HTML template literals
	vite-plugin-babel-jsx-to-literals	Vite wrapper for JSX→Literals Babel plugin

Labs — Literals (@literals)

	Package	Description
	html-css-minifier	Minify HTML template literal strings
	rollup-plugin-html-css-minifier	Rollup plugin for HTML literal minification
	parser	Parse template literals from code

Labs — Standalone tools

	Package	Description
	og-images-generator	OG image generator from HTML (no headless browser)
	vite-plugin-standard-css-modules	CSS modules via import attributes in Vite

Internal

	Package	Description
	@gracile/internal-tsconfigs	Shared TypeScript configuration presets
	@gracile/internal-utils	Shared monorepo utilities

👐 Contributing

See CONTRIBUTING.md.

---

• Documentation website (gracile.js.org)
• Documentation website repository
• Starter projects repository

---

“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”

― Antoine de Saint-Exupéry, Airman's Odyssey