Quick start

On this page

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:

component(s) embedded into a static .md template → more on component shortcodes here
route(s) built using a component framework as a templating language → more on component pages here
a netlify.toml configured to deploy in a flash → more on deployment here
an eleventy config with a few recommended defaults → more on config here

Add to your existing 11ty project

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

Installation

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.

Apply Slinkity as a plugin

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.

Development server

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 →

Production builds

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

11ty's standard production build
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 →

Add your first component shortcode

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()],
    })
  )
}

Slinkity is designed with Vue 3 in mind. Use Vue 2.x at your own risk!

First, install Vue 3 + the Slinkity Vue renderer:

npm i -D vue@3 @slinkity/vue

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 vue = require('@slinkity/vue')

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

First, install Svelte + the Slinkity Svelte renderer:

npm i -D svelte @slinkity/svelte

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 svelte = require('@slinkity/svelte')

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

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>

// _islands/GlassCounter.jsx
import { useState } from 'react'

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>

<!--_islands/GlassCounter.vue-->
<template>
  <p>You've had {{ count }} glasses of water 💧</p>
  <button @click="add()">Add one</button>
</template>

<script>
import { ref } from "vue";

export default {
  setup() {
    const count = ref(0);

    function add() {
      count.value += 1;
    }

    return { count, add };
  },
};
</script>

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

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

<!--_islands/GlassCounter.svelte-->
<script>
  let count = 0;

  function add() {
    count += 1;
  }
</script>

<p>You've had {count} glasses of water 💧</p>
<button on:click={add}>Add one</button>

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

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

This will do a few things:

Find _islands/GlassCounter.*. Note that we'll always look inside the _islands directory to find your components.
Prerender your component at build time. This means you'll always see your component, even when disabling JS in your browser (try it!).
"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 →