Import aliases

Slinkity configures a few import aliases out-of-the-box using Vite's alias feature. These allow convenient imports within your ES modules:

// import from a "utils" directory at the base of your project
import slinky from '/@root/utils/slinky'

slinky.goDownStairs()

And HTML files:

<head>
<!--import styles from your "_includes" directory-->
<link rel="stylesheet" href="/@includes/gorgeous-yellow-pink-gradient.scss">
</head>

List of aliases

The problem this solves: processing resources outside your output directory

Section titled "The problem this solves: processing resources outside your output directory"

Say our project is set up like so:

_site/ #build output
index.html
src/ #input
index.html
styles/
base.scss
import1.scss
import2.scss
...

Now, say we want to use that styles/base.scss in our src/index.html file. With a plain 11ty setup, we'd probably do the following:

  1. Wire up a sass command to compile that styles/base.scss file, and output a processed css file under _site/base.css
  2. Wire up an import in our index.html like so:
<head>
<link rel="stylesheet" href="/base.css">
</head>

Here, we're thinking in terms of what files will exist in our output folder once our build is complete (/base.css instead of /styles/base.scss).

How Vite changes the game

We can get much fancier with Vite at our disposal. Since html files are the bundler's entrypoint, we can use a direct path to our unprocessed scss file. Here's what we'd write under that same src/index.html file:

<head>
<link rel="stylesheet" href="../styles/base.scss">
</head>

...and bam! Vite will notice that scss file extension, and compile it to a browser-ready stylesheet on-the-fly.

However, you'll notice we needed to back out of our output directory to find the file. Relative paths like these can get pretty hairy when we start building nested routes (which could even have a different permalink between the input and output!). If we want to use absolute paths within our _site, we'll need to copy our scss file into the output directory using 11ty's addPassthroughCopy config option.

However, this can cause a problem for nested dependencies! Say we have a few scss fragments imported like so:

// /styles/base.scss
@use './import1.scss';
@use './import2.scss';

These are relative to the styles directory, so we'll need to copy import1 and import2 to the output directory for these imports to resolve. Heck, we'll probably copy our entire styles directory to be safe. I don't know about you, but copying directories of unprocessed resources to the "final" build directory doesn't sit well with me 😕

Enter import aliases

Let's try using an import alias instead:

<head>
<link rel="stylesheet" href="/@root/styles/base.scss">
</head>

Unlike that relative path from earlier, this resolves to an absolute path on our file system. Here's what Vite will look for on the other side:

/Users/SlinkityStan/Repositories/import-aliases-demo/styles/base.scss

Before you ask: no, this does not allow for unsafe file access on your machine! Vite will only process files inside the directory where it is run (aka wherever you run the slinkity command, which should be the base of your project).

With this, we can avoid unnecessary file copies to the build output and simplify our asset compilation. We expect many users to start removing addPassthroughCopy statements from their 11ty configs once they start using Vite to their advantage. This should speed up live reloading and production builds as well.