CascadiaJS Website

Platform and Services

This website is built on Enhance and deploys to Begin.

It currently depends on the following external services:

Customer.io - Mailing list

Enhance Structure

Enhance is an opinionated HTML web framework that renders pages on the server and supports progressive enhancement on the client for SPA-like experiences.

An Enhace app has two top-level directories: app and public.

The `app` Directory

The app directory contains all the code for our application, in addition to Markdown files that power many of the static webpages.

Disclaimer: Enhance is a new and rapidly changing web framework. We will do our best to keep this README up to date, but please reference the Enhance docs as the source of truth.

Here's a brief rundown of each subdirectory and its purpose:

api - controllers for paths in our web app, they generally call APIs and load data, which is passed to the view logic in pages
elements - custom elements that render and expand on the server
markdown - static Markdown files
pages - views (generally in HTML) that, if needed, render data passed from their API controller

The `public` Directory

This contains static files (images, css, etc).

Enhance makes all of these files available via the special /_public/ path off the root. In addition, this project has turned on fingerprinting, so when you deploy a file to the cloud (i.e. /images/logo.png), its filename is re-written with a unique hash attached (i.e. /images/logo-abc123.png) and when you reference this file in your markup (using just /images/logo.png), Enhance will re-write the response to the client on-the-fly to reference the filename with the attached hash.

App Design

For the most part, file-based routing makes it pretty clear what paths are supported by our app. For instance, the existence of pages/2024/index.mjs tells you that the app supports a /2024 web page.

Pages that require data to render are paired with an identically names JS file in the api directory.

There are two files named $$.mjs that live in the api and pages directories. The dollar sign ($$) functions as a wildcard and catches paths that are not defined by named files. This enables us to render Markdown files from the md directory based on the path requested:

/code-of-conduct will render markdown/code-of-conduct.md
/2024/cfp will render md/2024/cfp.md

If there is no Markdown file that matches the path, a 404 error will be returned.

Install

clone this repo
npm i
install the Begin CLI, see instructions here

Setup

If you need to run/test the mailing list subscription action (POST /signup) you will need to configure the following environment variables: CIO_SITE_ID, CIO_API_KEY, CIO_APP_KEY

Run dev server

npm start

Generating social sharing images for speakers and other web pages

You'll need to install puppeteer globally first:

PUPPETEER_EXPERIMENTAL_CHROMIUM_MAC_ARM=true npm i puppeteer -g

Then link it so that you can run the script

npm link puppeteer

Making contributions

If you would like to make a contribution, please fork this repo and send us a pull request.

kold-stytch/cascadiajs