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
   • Autopilot
5. Roadmap
li>To Do
6. Contributing
7. License
8. Contact
9. Acknowledgments

🥱 TL;DR

An starter project for Eleventy with an opinionated workflow – Keeping Eleventy in control of the entire development and build processes.

    gh repo clone edheltzel/flightdeck flightdeck && cd flightdeck && bun install && bun start

Build your project

   bun 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 have shifted to using Bun as our primary package manager.

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

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
bun install

Using gh in the terminal:

gh repo clone edheltzel/flightdeck

cd flightdeck
bun install

see all dependencies

    bun pm ls
/Users/ed/Developer/personal/flightdeck/for-11ty-esbuild node_modules (583)
├── @11ty/eleventy@2.0.1
├── @11ty/eleventy-img@4.0.2
├── @11ty/eleventy-navigation@0.3.5
├── @11ty/eleventy-plugin-syntaxhighlight@5.0.0
├── @alpinejs/persist@3.13.8
├── @biomejs/biome@1.6.4
├── alpinejs@3.13.8
├── browserslist@4.23.0
├── eleventy-plugin-embed-everything@1.18.2
├── esbuild@0.20.2
├── fast-glob@3.3.2
├── html-minifier@4.0.0
├── lightningcss@1.24.1
├── lightningcss-cli@1.24.1
├── markdown-it@14.1.0
├── markdown-it-attrs@4.1.6
├── stylelint@16.3.1
└── stylelint-config-standard@36.0.0
  

(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 start

Available Run Commands

package.json scripts (11 found):
$ bun run start
eleventy --serve
$ bun run build
pnpm run clean && pnpm run build:11ty
$ bun run build:11ty
cross-env ENV=production eleventy
$ bun run debug
DEBUG=Eleventy* eleventy
$ bun run preview
bunx http-server dist -p 4000
$ bun run check
biome check
$ bun run format
biome format
$ bun run lint
biome lint
$ bun run lint:css
stylelint "src/**/*.css" --fix
$ bun run clean
./.scrub.sh site
$ bun run purge
./.scrub.sh purge

• 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.
• 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, see biome.json.
  • ie: bun run check ./src/assets/js/app.js
• format command - uses biome to format JS/TS, see biome.json.
  • ie: bun run format ./src/assets/js/app.js
• lint command - uses biome to lint JS/TS, see biome.json.
  • ie: bun run lint ./src/assets/js/app.js
• lint:css command - uses stylelint to find issues in your css.
• 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 bun. - 🧼 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 bun upgrade not working as expected or how other package managers work.

(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 ./_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 ./_flightdeck directory, you will find the following directories:

• ./_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.
• ./_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.
• ./_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.

• ./_flightdeck/filters.js
• ./_flightdeck/plugins.js - this file controls Eleventy plugins that modify content.
• ./_flightdeck/shortcodes.js
• ./_flightdeck/transforms.js
• ./_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 write scss, please install sass and eleventy-plugin-sass and update the transform.js file to use the module. You'll need to remove the lightingcss module and update the styles directory to your scss files.

bun install sass eleventy-plugin-sass

👨‍🚀 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)

🧭 Roadmap

• Improve documentation
• Create a theme using Autopilot UI Components
• Add Dockerfile
• Add Yeoman generator/npm package
• Add our Eleventy plugins

📝 To Do

• 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)