A personal starting point for building static sites with eleventy using netlify CMS for content.
Visit the live site for this repo
- lots of opinions
- lots of comments
- more code than is sensible for an effective starter
I use this repo to keep minimal examples of common problems I need to solve on static sites.
It is useful as a reference but delete all the bits you don't want before you use it!
colorthief causes builds to fail due to a deep dep issue.
Currently using this workaround: lokesh/color-thief#206 (comment)
- Built with eleventy
- Using Nunjucks, JSON and JavaScript to template content
- Data generated through netlify CMS
- Templates and examples integrate netlify CMS with eleventy
- Includes custom netlify CMS widgets to simplify image handling and admin layout
- Styled using modern CSS transformed with postcss-preset-env
- Browser prefixes added with Autoprefixer
- Minified with CSS nano
- All through PostCSS
- linted by stylelint
- Client script transpiled by babel
- Svelte for progressively enhanced components
- Bundled by webpack
- Linted by eslint
- Served in development by light-server
- make this readme more useful for when nothing makes sense in a few months.
- move custom image widgets into their own repo
- revisit image handling once these issues are resolved. See Cloudinary for images below.
Explanations of the thought process behind decisions made in this starter
Moving away from a huge webpack config : Traditionally I have used webpack to handle all aspects of bundling, linting, transpiling, etc. which is very useful when using webpack's dev server but results in huge config files.
With this project I've tried to use individual tooling more directly from the scripts in package.json
light-server is very useful in helping to achieve this because it gives me an easy way to watch multiple files, run browser sync and run npm commands on changes.
Modern JS for browsers that support modules: This is currently a little complex but will hopefully become simpler over time!
Serving more modern code (less babel transformations) to modern browsers by targeting browsers that support modules (browser support is a very good 88%+ of traffic) is widely recommend and gives big file size savings to modern browsers. However there are several implementation details that are tricky! Modern Script Loading by Jason Miller is probably the best reference to the multiple problems of serving code in this way.
This is handled by the webpack config. We output two configs, one which uses @babel/preset-modules for modern browsers and the other which uses @babel/preset-env.
We are currently using a bit of inline JavaScript to detect support and serve the correct file. Additionally we use preload tags to preload the modern script (older script is not preloaded). This method is discussed in more length on the next.js repo.
If we decide not to use this inline JavaScript then Option 3 from Modern Script Loading would be a strong candidate for an alternative. It's the method preact-cli use.
There's an argument that if our no JavaScript version of the site is strong enough we could serve no JavaScript at all to browsers that don't support a basic subset of features. We could potentially only serve the modern JS and just let older browsers use the JavaAScript free version of the site or we could cut the mustard like the BBC did in the past by adding feature detection to our inline JavaScript that writes out the script tags.
We can determine what features to detect or whether to serve the fall-back JavaScript on a per-project basis.
👻 to do: outline some coherent examples from real projects or bring in small examples...
👻 to do: outline some coherent examples from real projects or bring in small examples...
GLADD is a live site built from this starter that uses Svelte extensively in the membership areas...
Using modern CSS with PostCSS and postcss-preset-env: Previously I have used Sass heavily but in this starter I'm trying to use native (or upcoming) features of CSS.
I'm trying not to use too many experimental features but details of the features that are enabled and a more in depth look at CSS structure can be found in src/styles/readme.md.
Things to remember or gotchas
This repo is setup to use Cloudinary as the media library for netlify CMS. There were multiple reasons behind this decision but primarily it is easier to handle responsive images with a Cloudinary integration.
For a new project: remember to set up new Cloudinary settings in the config file!
We initially planned to store the primary image upload in the repo (so that we had ownership of content and it was all centrally located) and then use Cloudinary to fetch remote images to generate and serve the various responsive sizes. However, currently, storing images in the repo can be unintuitive. Specifically we had issues with previews, validation etc. becoming unavailable until builds had completed. This is currently being addressed so we may change the way we handle media going forwards!
We use node-file-rev for cache busting, currently we manually specify which files to cache bust in the npm run rev script. This is simple but if you generate lots of individual files that need to be cache busted it could be worth looking at automating this a little more.
We load a small fetch polyfill in the head of _includes/layouts/base.njk. If you don't need it, delete it!
Most other required polyfills are bundled with our code by Core JS thanks to the Babel preset-env but fetch isn't polyfilled by Core JS
Because all browsers that support ES modules also support fetch we use nomodule to avoid loading this script when it isn't required. If you want to load other polyfills you should check whether this method of loading is suitable
We are authenticating access to our GitHub repo using the process outlined in the netlify CMS docs. This only works because Netlify is providing the server side aspect.
If we were not hosting on Netlify (or didn't want them involved in authentication) but wanted to continue using netlify CMS we could look at using client side authentication with something like implicit grants in GitLab
As a result, the config for authentication is located largely on netlify
- Accessed at
/admin/(that trailing slash is important for it to work) - Remember: when running locally changes are still pushed to the remote repo