Installation

Start developing with Gracile in less than 1 minute ⏳.
You can either use the CLI, a starter template, convert an existing Vite project, or start from scratch.

The “Create” command

This is the quickest way to create a preconfigured project with Gracile.

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

See all create-gracile CLI options.

Requirements

Fetch a starter project

This is an alternative way to create a preconfigured project with Gracile.

Shallow clone a starter project from the repository with the degit command.

npx degit gracile-web/starter-projects/templates/minimal-static my-project

cd my-project
npm run dev

See the starter list..

Install manually

Naturally, you can also start a project from scratch.
Here is a minimal boilerplate.

package.json

{
  "name": "my-gracile-project",
  "type": "module",
  "version": "0.0.0",
  "private": true,

  "scripts": {
    "dev": "vite",
    "check": "tsc",
    "build": "vite build",
    "preview": "vite preview"
  },

  "dependencies": {
    "@gracile/gracile": "latest",
    "vite": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "typescript": "latest"
  }
}

For a server build, you can use these extra shorthands:

{
  "scripts": {
    // ...
    "preview": "node --watch -C preview server.js",
    "start": "node server.js",
     Or with a TypeScript runner.
    "preview": "tsx --watch -C preview server.js",
    "start": "tsx server.js",
  },
}

The -C stands for --conditions.

You’ll find that Gracile relies fairly on Node’s export conditions.
Here, it’s useful to get the logger running, while it’s not in production (the default).

Those are just hints, it’s up to you to integrate with your favorite workflow, like using tsc + node --watch instead of tsx etc.
The server is running separately from Vite, it’s totally outside the Gracile/Vite realms.

Packages installation

npm install @gracile/gracile

# Next version, in development
npm install @gracile/gracile@next

# Addons…
npm install \
@gracile/metadata \
@gracile/svg \
@gracile/sitemap \
@gracile/markdown
# ...

See all add-ons.

The @next tag can be used for any @gracile/* package.
That way, you will get a preview of the unreleased builds.

Lit (optional)

npm install lit

Note

lit exports the html template literal which can be used for both client and server.
However, for a fully static website, the server-only html is enough.
It’s the @lit-labs/ssr’s html which is re-exported from @gracile/gracile/server-html.

Lit exports some utilities that you’ll find useful, even if you’re not using hydration and other client features at all.

TypeScript tsconfig.json extendable presets

Three levels of type safety are available with these presets: base, strict or strictest.

{
  "extends": "@gracile/gracile/tsconfigs/strictest", // Or `base` | `strict`
}

Ambient typings

📄 /ambient.d.ts


/// <reference types="@gracile/gracile/ambient" />

 For add-ons and third-parties…
/// <reference types="@gracile/markdown/ambient" />
/// <reference types="@gracile/svg/ambient" />
// ...

Requirements

Note

Once Gracile become stable (reaching v1), the Gracile main package (@gracile/gracile) will be transferred to the gracile package (without the @ scope).