flightdeck

An opinionated starter project for Eleventy 🎈.

📔 Table of Contents

1. TL;DR
2. About The Project
   • Inspiration
   • Dependencies
   • Built With
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
   • Use Sass/Scss
   • Autopilot
5. Known Issues
   • Markdown workarounds
6. Roadmap
To Do
7. Contributing
8. License
9. Contact
10. Acknowledgments

🥱 TL;DR

A starter project for Eleventy with an opinionated workflow

The key concept here is to keep Eleventy in control of the entire development and build processes.

    gh repo clone edheltzel/flightdeck flightdeck && cd flightdeck && pnpm run install && pnpm run start

Build your project

   pnpm run build

🌟 About The Project

The flightdeck objective is to provide a unified starting point for all your Jamstack websites, by leveraging popular static-site-generators (SSG).

This flavor of flightdeck uses Eleventy with an opinionated workflow without the support additional tools like Webpack, Parcel, or Gulp. This is to keep things simple and to keep Eleventy in control of the entire development and build processes.

💡 Inspiration

Like other versions of flightdeck, this is just an adaptation of the original flightdeck project that uses Jekyll for its static site generation and Gulp for all assets bundling. ►►► 🫠 For other versions of flightdeck, 👉 look here

Jérôme Coupé's post Structuring Eleventy Projects served as inspiration for how this project is structured and over-time, things will shift as ideas change, but in 2022, we are shamelessly adopting the concept Jérôme Coupé outlines.

(back to top)

👾 Tech Stack

• Eleventy
• ESBuild
• Nunjucks
• Biome
• LightningCSS
• Jampack
• Sass

(back to top)

🧰 Getting Started

All version of flightdeck use NodeJS. So a very minimal and basic knowledge of Node and Git should be had when using flightdeck as your launchpad.

In the future, we plan to include Docker and make all flightdeck starters available as a Yeoman and/or NPM package.

🧯 Prerequisites

We are assuming that you already have Node with NPM (or another package manger, like Bun/Pnpm/Yarn) and Git installed on your system – it is also ideal that you have the latest LTS release of Node. As of this writing the current LTS release is 20.12.2

🤖 Dependencies

Package Managers

Package managers are like dotfiles, everyone has their own preference.

We are using pnpm as our package manager.

But, you can swap pnpm in favor of your preferences 👉 NPM , Yarn, and and Bun. Use whatever you want 👍 just be sure to update the package.json with what ever flavor you choose to use:

• change preview with your preference
• change upgrade with your preference
• remove packageManager from package.json

Corepack Deprecated 🚪

Node.js Takes Steps Towards Removing Corepack by Sarah Gooding

If you're using an older version of Node, it's highly recommended that you enable Node's corepack, this way Yarn and PNPM are included in your toolbox without the need to install them separately.

Please be aware that this certainly won't be the most recent version of PNPM/Yarn.

• pnpm and yarn

  corepack enable
  
  corepack prepare pnpm@latest --activate
  corepack prepare yarn@latest --activate

⚙Installation

Using git in the terminal:

git clone https://github.com/edheltzel/flightdeck.git

cd flightdeck
pnpm run install

Using gh in the terminal:

gh repo clone edheltzel/flightdeck

cd flightdeck
pnpm run  install

see all dependencies

 Legend: production dependency, optional only, dev only

 [email protected] ~/Developer/flightdeck-esbuild

 dependencies:
 @alpinejs/persist 3.14.1
 alpinejs 3.14.1
 upgrade 1.1.0

 devDependencies:
 @11ty/eleventy 3.0.0
 @11ty/eleventy-img 5.0.0
 @11ty/eleventy-navigation 0.3.5
 @11ty/eleventy-plugin-syntaxhighlight 5.0.0
 @biomejs/biome 1.9.3
 browserslist 4.24.0
 eleventy-plugin-embed-everything 1.19.0
 esbuild 0.24.0
 fast-glob 3.3.2
 html-minifier 4.0.0
 lightningcss 1.27.0
 lightningcss-cli 1.27.0
 markdown-it 14.1.0
 markdown-it-attrs 4.2.0
 markdown-it-bracketed-spans 1.0.1

(back to top)

🏃‍♂️ Run Locally

There are just a few npm-:150 available, but the start command is where all the magic 🪄 happens – it will spin up the development server from Eleventy.

Again, the focus here is to keep Eleventy in control of the entire development and build processes, to keep things simple.

pnpm run start

Available Run Commands

Lifecycle scripts:
start
eleventy --serve

Commands available via "pnpm run":
 dev
  pnpm run clean && pnpm run start
 build
  ENV=prod eleventy
 debug
  DEBUG=Eleventy* eleventy
 deploy
  wrangler pages deploy dist --project-name my-flightdeck --commit-message "local build & deploy"
 preview
  pnpm run clean && pnpm run build && pnpx http-server dist -p 54321
 check
  biome check
 format
  biome format --
 lint
  biome lint --
 clean
  ./.scrub.sh site
 purge
  ./.scrub.sh purge
 upgrade
  pnpx npm-check-updates -ui
 release
  gh release create v$npm_package_version --generate-notes --latest

• preinstall command - runs npx only-allow pnpm to ensure that only pnpm is installed.
• dev command - removes the existing dist and starts the development server with Eleventy.
• start command - starts the development server with Eleventy.
• build command - executes the production build of your site with Eleventy, includes HTML minification, compressed Sass, optimized images, and bundled javascript.
  • for our workflow, Cloudflare handles the DNS while Cloudflare Pages does the building and hosting - Cloudflare's Auto Minify minifies the HTML, CSS, and JS. You can easily add minification to the build process by adding a plugin to Eleventy.
• debug command - runs the development server with Eleventy with debug logging enabled.
• deploy command - deploys the "manual" production build to Cloudflare Pages.
• preview command - spins up a local server to preview the production build.
• check command - runs biome lint and format at the same time JS/TS/CSS, see biome.json.
  • ie: pnpm run check ./src/assets/js/app.js
• format command - uses biome to format JS/TS/CSS, see biome.json.
  • ie: pnpm run format ./src/assets/js/app.js
• lint command - uses biome to lint JS/TS/CSS, see biome.json.
  • ie: pnpm run lint ./src/assets/js/app.js
• clean command - scrubs/removes the dist/ and .cache directories
• purge command - scrubs/removes the dist/, .cache, node_modules, and any lock files from npm, yarn, pnpm or pnpm. - 🧼 A fresh install.
  • 👀 NOTE: Both clean and purge are executed from a bash script
• upgrade command - uses bunx npm-check-updates -ui to upgrade dependencies to their latest versions and updates the package.json - this is a work around for pnpm run upgrade not working as expected or how other package managers work.
• release command - creates a new release on GitHub.

(back to top)

‍🚀 Deployments

Deployments for this project are completely up to you and your needs, we are fans of Cloudflare Pages, which is why you'll find a .node-version file, Cloudflare Pages currently supports Node v18.17.1. Some other really good and popular options are GitHub Pages, Vercel, Netlify, and Render. Your call on what you use.

Note - Environment Variables

Don't forget to create your own .env with whatever environment variables you need for your project.

(back to top)

📁 File Structure

flightdeck is a very opinionated starter kit, so the file structure is very specific to our needs. All the Eleventy configuration is done in the .eleventy.js file, but it is broken down into sections for easier navigation and maintain. All Eleventy configuration options are available, see the Eleventy Docs for more information.

File Structure

.
├── _flightdeck
│  ├── filters
│  ├── shortcodes
│  └── transforms
└── src
  ├── _includes
  │  ├── components
  │  ├── data
  │  ├── layouts
  │  ├── macros
  │  ├── partials
  │  └── utilities
  ├── _static
  ├── assets
  │  ├── fonts
  │  ├── images
  │  │  └── spacex [optional]
  │  ├── js
  │  │  └── modules
  │  │     ├── alpineModules
  │  │     └── visualGuidanceSystem
  │  └── styles
  │     ├── _autopilot
  │     │  └── _base
  │     │  └── _components
  │     │  └── _layouts
  │     │  └── _utilities
  │     │  └── _vendors
  └── collections
      ├── blog
      └── pages

👀 Usage

The core concept of flightdeck to keep 11ty in charge of all the DX so you can focus on creating content.

flightdeck makes a lot of assumptions and is very opinionated - but having a good idea of how Eleventy's data cascade works is always nice, as well as having some understanding on template inherence in Nunjucks will go a long way. But is not needed

For making changes to the way flightdeck pilots Eleventy, you will want to reference the ./src/_flightdeck directory. This is where all the Eleventy configuration is done, but it is broken down into sections for easier navigation and maintainability.

Inside the ./src/_flightdeck directory, you will find the following directories:

• ./src/_flightdeck/filters - where all Universal filters are added to Eleventy templates. Currently we use Nunjucks for our templates, so all filters are added to the Nunjucks environment, but are easily adapted to other template engines, like Liquid.
• ./src/_flightdeck/shortcodes - where all shortcodes are added to extend the functionality of the content you are creating. We consider shortcodes content altering and not UI focused. The idea is to create shortcodes that make writing content easier and more enjoyable.
• ./src/_flightdeck/transforms - where all transforms are added to templates, javascript, styles, and images.

All the directories have a corresponding file that is used to import all the files in the directory. Each of these files are imported into .eleventy.js as modules.

• ./src/_flightdeck/filters.js
• ./src/_flightdeck/plugins.js - this file controls Eleventy plugins that modify content.
• ./src/_flightdeck/shortcodes.js
• ./src/_flightdeck/transforms.js
• ./src/_flightdeck/workflow.js - this file controls the Eleventy dev server.

flightdeck comes with a custom image transform plugin that watches for changes in the ./src/assets/images directory and then optimizes any new or changed images, copies it to the output destination directory ./dist/assets/images. Since we are using the the Eleventy Image Plugin under-the-hood, it is smart enough to know if an image has already been optimized, we don't need to worry about that. Just set it and forget it.

PLEASE NOTE: This feature does add a little overhead to the initial build process, which is why it is disabled by default.

If you would like the enable this feature just set useImageDirTransform: true in .eleventy.js and you're good to go.

All Eleventy configuration options are available, see the Eleventy Docs for more information.

If you're looking to extend or further configure your project with other NPM modules, Eleventy plugins, or ESBuild Plugins, just reference the appropriate documentation.

• Eleventy Docs
• Nunjucks Docs
• ESBuild Docs
• Biome Docs
• LightningCSS Docs
• Sass Docs
• NPM Package Docs

💅 Using Sass/Scss

If you'd rather us Scss to write you styles you'll need to do a few things to set it up:

1. Install sass, eleventy-plugin-sass, postcss, and autoprefixer
   • see eleventy-sass repo for documentation.
2. Update the src/_flightdeck/transform.js file and the src/_flightdeck/transforms/_scss.js
3. Make sure to remove the lightningcss module
4. Update your src/assets/styles directory to fit your Scss workflow.

• If you want to still use Scss, it is still apart of the package dependencies along with PostCSS.
  • please reference _flightdeck/transforms.js and _flightdeck/transforms/_scss.js
  • see eleventy-sass repo for documentation.
  • see picocss docs for theming.
• If you do not want the additional dependencies just run pnpm remove sass eleventy-sass postcss autoprefixer @picocss/pico

👨‍🚀 Autopilot Theme

WIP Autopilot, is a custom minimal css framework for semantic HTML.

The goal of Autopilot, is to provide a simple, yet powerful, set of default styles to help build your UI components.

(back to top)

🐛 Known Issues

Markdown workarounds

When using the markdown-it-attrs plugin, you'll encounter a build issue when applying IDs to elements, using the {#id} syntax. This is a result of setting the Eleventy config to use Nunjucks as the template engine for markdown files -> markdownTemplateEngine: "njk". Which in turn treats the {# as the start of a Nunjucks comment. To work around this, use the attribute syntax {id=id} instead of {#id}.

🧭 Roadmap

• Improve documentation
• Create a theme using Autopilot UI Components
• Add Dockerfile
• Create npm package to quickly install flightdeck

📝 To Do

• add 11ty plugin bundle
• create layout with new grid system
• improve nunjucks layouts and partials
• document the new grid system
• review lightncingcss for more performance options
• replace scss with lightncingcss
• combine autopilot and declarative scaffold
• update naming convention to be consistent
• update layouts to use sematic markup for containers
• add utility classes for grid correctly
• update the style guide to use the grid utility classes

See the open issues for a full list of proposed features (and known bugs/issues).

(back to top)

👋 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

⚠️ License

Distributed under the WTFPL License. See LICENSE for more information.

(back to top)