Skip to main content

Quick start

Use our handy CLI command to spin up a Slinkity site: npm init slinkity. This demos our core functionality while staying as lean as possible, making it the perfect launchpad for new projects 🚀

It includes:

Want to bring Slinkity to your current 11ty project? No sweat! Slinkity is built to slot into your existing workflow 😁

First, install Slinkity + the latest 11ty into your project:

npm i --save-dev slinkity @11ty/eleventy@canary

Slinkity requires Node v14 and up. You can check your version by running node -v in your terminal before trying Slinkity.

Slinkity is an 11ty plugin you can add and configure in your existing 11ty config:

// .eleventy.js or eleventy.config.js
const slinkity = require('slinkity')

module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(slinkity.plugin, slinkity.defineConfig({
// optional: use slinkity.defineConfig
// for some handy autocomplete in your editor
}))
}

You may want one of our pre-built component renderers for Preact, Vue, or Svelte support too. To setup those config options, jump to the "add your first component shortcode" section.

Slinkity attaches Vite to 11ty's built-in development server as middleware, so you can keep using the --serve CLI flag as you'd expect. Still, we recommend starting your server with the following CLI flags:

eleventy --serve --incremental --quiet
  • --incremental will prevent any flashes of unstyled content (FOUC) during Vite's page reloads. It'll also show your changes in the browser much faster.
  • --quiet will hide extraneous logs in your console. Since Vite already describes changes with informative live reload and HMR logs, it's best to silence duplicate information from 11ty.

For more configuration details, head to:

The Slinkity configuration guide →

With Slinkity in the mix, your production builds will now complete in 2 steps:

  1. 11ty's standard production build
  2. Vite's production build to bundle JS and CSS assets

Don't worry, your output directory and build config options won't be affected! Though you may need to move static assets to a separate /public directory (including your robots.txt, sitemap, and other related assets). To learn more about asset handling, head to:

Managing assets for production builds →

Let's try adding components to your 11ty project. Say you have a project directory with just 1 file: index.njk. That file might look like this:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Slinkity time</title>
</head>
<body>
<h1>Look ma, it's Slinkity!</h1>
</body>
</html>

If you run this using the eleventy --serve --incremental command, you'll just see the gloriously static text "Look ma, it's Slinkity!"

But what if we want something... interactive? For instance, say we're tracking how many glasses of water we've had today (because hydration is important!). If we know a little JavaScript, we can whip up a counter using our favorite flavor of components.

First, we'll need one of our "renderers" to handle React, Vue, and/or Svelte:

First, install Preact + the Slinkity Preact renderer:

npm i -D preact @slinkity/preact

Then, add this renderer to a slinkity.config.js at the base of your project:

// .eleventy.js or eleventy.config.js
const slinkity = require('slinkity')
const preact = require('@slinkity/preact')

module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(
slinkity.plugin,
slinkity.defineConfig({
renderers: [preact()],
})
)
}

First, install React's suite of dependencies + the Slinkity React renderer:

npm i -D react react-dom @slinkity/react

Then, add this renderer to a slinkity.config.js at the base of your project:

// .eleventy.js or eleventy.config.js
const slinkity = require('slinkity')
const react = require('@slinkity/react')

module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(
slinkity.plugin,
slinkity.defineConfig({
renderers: [react()],
})
)
}

Now, we can write a component under the _includes/ directory like so:

// _islands/GlassCounter.jsx
import { useState } from 'preact/hooks'

function GlassCounter() {
const [count, setCount] = useState(0)
return (
<>
<p>You've had {count} glasses of water 💧</p>
<button onClick={() => setCount(count + 1)}>Add one</button>
</>
)
}

export default GlassCounter

Finally, let's place this component onto our page with a component shortcode:

...
<body>
<h1>Look ma, it's Slinkity!</h1>
{% island 'GlassCounter.jsx', 'client:load' %}{% endisland %}
</body>

This will do a few things:

  1. Find _islands/GlassCounter.*. Note that we'll always look inside the _islands directory to find your components.
  2. Prerender your component at build time. This means you'll always see your component, even when disabling JS in your browser (try it!).
  3. "Hydrate" that prerendered component with JavaScript. This is thanks to our client:load directive.

Now in your browser preview, clicking "Add one" should increase your counter 🎉

Learn more about component shortcodes →