Express

Frameworks

Express

Using Express with a frontend framework?
Follow the React, Vue, or Svelte page instead, since their setup differs.

Usage

Link to This Section

In a bare-minimum Express app, the following works as expected:

import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send(`
    <!doctype html>
    <html>
      <head>
        <link rel="stylesheet" href="https://ka-f.webawesome.com/webawesome@3.10.0/styles/webawesome.css" />
        <script type="module" src="https://ka-f.webawesome.com/webawesome@3.10.0/webawesome.loader.js"></script>
      </head>
      <body>
        <wa-page>
          <wa-button>Hello World</wa-button>
        </wa-page>
      </body>
    </html>
  `);
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

The key piece is loading Web Awesome's stylesheet and loader in your <head>:

<head>
  <link rel="stylesheet" href="https://ka-f.webawesome.com/webawesome@3.10.0/styles/webawesome.css" />
  <script type="module" src="https://ka-f.webawesome.com/webawesome@3.10.0/webawesome.loader.js"></script>
</head>

There are other ways to set up Web Awesome, such as with npm or downloading ZIP files, which are documented on the Installation page.

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

Add SSR

Server-Side Rendering

Link to This Section

SSR works by rendering your HTML through Lit on the server. First, install Web Awesome locally:

npm install @awesome.me/webawesome

Then add the SSR setup to the top of your server. This registers the components and tells Lit to run each one's connectedCallback while rendering:

// Register all Web Awesome components on the server
import '@awesome.me/webawesome/dist/ssr.js';
// renderString turns an HTML string into a Lit template, runs SSR, and returns a string
import { renderString } from '@awesome.me/webawesome/dist/ssr/render-string.js';
import { LitElementRenderer } from '@lit-labs/ssr';

LitElementRenderer.renderOptions.push(element =>
  element.localName.startsWith('wa-') ? { connectedCallback: true } : undefined,
);

Finally, wrap each HTML response in renderString():

- res.send(`...your HTML...`);
+ res.send(renderString(`...your HTML...`));

// Register all Web Awesome components on the server
import '@awesome.me/webawesome/dist/ssr.js';
// renderString turns an HTML string into a Lit template, runs SSR, and returns a string
import { renderString } from '@awesome.me/webawesome/dist/ssr/render-string.js';
import { LitElementRenderer } from '@lit-labs/ssr';
LitElementRenderer.renderOptions.push(element =>
  element.localName.startsWith('wa-') ? { connectedCallback: true } : undefined,
);

import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send(
    renderString(`
    <!doctype html>
    <html>
      <head>
        <link rel="stylesheet" href="https://ka-f.webawesome.com/webawesome@3.10.0/styles/webawesome.css" />
        <script type="module" src="https://ka-f.webawesome.com/webawesome@3.10.0/webawesome.loader.js"></script>
      </head>
      <body>
        <wa-page>
          <wa-button>Hello World</wa-button>
        </wa-page>
      </body>
    </html>
  `),
  );
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Using a View Engine

Link to This Section

If you use a view engine such as Pug, Haml, or Nunjucks, add a middleware that runs each rendered view through renderString. It reuses the same SSR setup from above:

This middleware transforms every response through Lit.
If a route can return non-HTML like JSON or CSV, add a content-type check so it skips the transform.

app.set('view engine', 'nunjucks');

// Transform each rendered view through Lit before sending
app.use((req, res, next) => {
  const original = res.render.bind(res);

  res.render = (view, options, callback) => {
    if (typeof options === 'function') {
      callback = options;
      options = {};
    }

    original(view, options, (err, html) => {
      if (err) return typeof callback === 'function' ? callback(err) : next(err);
      const out = renderString(html);
      return typeof callback === 'function' ? callback(null, out) : res.send(out);
    });
  };

  next();
});