Build Awesome (11ty)

Frameworks

Build Awesome (11ty) is relatively unopinionated, so there are several ways to add Web Awesome — the simplest is via npm, which your project most likely already uses.

Installation

Link to This Section

To add Web Awesome to your Build Awesome site, install the package from npm.

npm install @awesome.me/webawesome

Usage

Link to This Section

Copy the Assets

Link to This Section

Web Awesome's assets must be available to the browser. Add addPassthroughCopy to your eleventy.config.js to copy them into your build output — create the file if you don't have one yet:

// eleventy.config.js

const webawesomeDir = './node_modules/@awesome.me/webawesome';

export default async function (eleventyConfig) {
  eleventyConfig.addPassthroughCopy({
    webawesomeDir: 'webawesome',
  });
}

export const config = {
  markdownTemplateEngine: 'njk',
  dir: {
    input: 'pages',
    includes: '_includes',
    layouts: '_layouts',
  },
  templateFormats: ['njk', 'md'],
};

Load the Styles & Loader

Link to This Section

Add the stylesheet and component loader to your layout's <head>:

<head>
  <link href="/webawesome/dist-cdn/styles/webawesome.css" rel="stylesheet">
  <script type="module" src="/webawesome/dist-cdn/webawesome.loader.js"></script>
</head>

Web Awesome is ready to use.
Want server-side rendering too?

Add SSR

Server-Side Rendering

Link to This Section

With server-side rendering, your Web Awesome components render to HTML on the server, so pages display fully styled before client-side JavaScript loads. Learn more in the SSR docs.

To add SSR support to Build Awesome (11ty), follow the steps below.

Install the Plugin

Link to This Section

Install the @lit-labs/eleventy-plugin-lit plugin from npm:

npm install @lit-labs/eleventy-plugin-lit

Register the Plugin

Link to This Section

Once installed, register the plugin in your eleventy.config.js file.

// eleventy.config.js

import litPlugin from '@lit-labs/eleventy-plugin-lit';
import * as fs from 'node:fs';
import * as path from 'node:path';

const webawesomeDir = './node_modules/@awesome.me/webawesome';
const webawesomeComponentsDir = path.join(webawesomeDir, 'dist', 'components');
const webawesomeComponents = fs.readdirSync(webawesomeComponentsDir).map(componentName => {
  return path.join(webawesomeComponentsDir, componentName, componentName + '.js');
});

export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(litPlugin, {
    mode: 'worker',
    componentModules: webawesomeComponents,
  });

  eleventyConfig.addPassthroughCopy({
    webawesomeDir: 'webawesome',
  });
}

export const config = {
  markdownTemplateEngine: 'njk',
  dir: {
    input: 'pages',
    includes: '_includes',
    layouts: '_layouts',
  },
  templateFormats: ['njk', 'md'],
};

Swap in the SSR Loader

Link to This Section

Update your layout to use the SSR loader instead of the default loader:

<head>
  <link href="/webawesome/dist-cdn/styles/webawesome.css" rel="stylesheet">
  <script type="module" src="/webawesome/dist-cdn/webawesome.ssr-loader.js"></script>
</head>