https://frontenso-11ty-starter.netlify.app/
- Jamstack compatible 11ty Boilerplate
- Netlify demo page
- Features
- Getting started
- Component-based Approach
- Modern Image Formats
- Image Quality Settings
- TypeScript (optional)
- TailwindCSS (optional)
- Nunjucks HTML template engine
- Using a different template engine
- Webpack v5
- Customize static path
- .env file and environment variables
- The SVG sprite
- {% image %} Nunjucks tag
- Inlining images as base64 strings inside Nunjucks templates using
inlinefilter - Inlining raster or svg images in CSS
- Example of using
ifstatement in an HTML attribute - Examples
- Useful links
This starter kit is built on a component-based structure, utilizing the power of Nunjucks, SCSS, and TailwindCSS (with a Just-in-Time compiler), Webpack, ESNext, and live reloading. Modern image formats out of the box (AVIF, WebP) and image optimization.
It uses 11ty to handle HTML generation and Gulp for the rest of the build process.
Core features:
- Component-based approach.
- Fast builds with Gulp and SCSS support.
- Modern image formats out of the box (AVIF, WebP) and image optimization.
- No JS-framework dependencies (you can add preact or any other framework though).
- Live reloading.
- Linters included.
- Webpack config for most cases.
- (Optional) TailwindCSS with JIT.
- (Optional) TypeScript support using JSDoc notation.
It is flexible and can be used in conjunction with any data source, whether it be a headless CMS, JSON, Markdown or any other data source that can be fetched via JavaScript. For more information on how to work with data sources, please refer to the 11ty documentation.
This repository can be a perfect starting point for your next project. By simply clicking on the green "Use this template" button on this GitHub page, you can easily create a new repository. After creating a new repository you can customize and configure it to your liking and begin your development journey with ease.
npm install
npm start
3. Open development URL - http://localhost:9000/.
npm run build
npm run zip
This command uses npm run build to build the project and then creates a zip-archive build.zip in the root folder of the project.
Decomposing the UI into separate, less coupled components is highly recommended for many reasons.
It is a best practice to create components for parts of the UI that appear in multiple places in your project, such as buttons, common page sections, widgets, and sliders.
To keep your components organized, it is a good idea to keep them inside the src/components/ folder. This starter kit allows you to keep the markup, styles, and JavaScript code for a component all in one place, making it easy to use them in multiple locations throughout your project. Take a look at the src/components/ folder for examples of how different types of components are arranged. It's important to note that it is not always necessary to include Nunjucks or JavaScript code for a component if it does not make sense to do so, for example, when the markup is quite simple or when a component does not have any JavaScript logic.
This starter uses @11ty/eleventy-img to generate modern image formats (AVIF, WebP) and optimize images. See examples on the demo page.
You can change image compression settings for avif, webp, jpeg files in .eleventy.js config.
Png are compressed with pngquant as it provides the best compression. You can change png compression settings in optimize-png.js config.
This boilerplate has built-in support for TypeScript, but it is completely optional to use it during development. We have chosen to use JSDoc notation (which is officially supported by TypeScript team) to provide TypeScript support. This means that you don't have to write your code using TypeScript syntax, and can instead continue to write your code using JavaScript syntax with JSDoc notation for TypeScript support. This approach also allows you to easily disable TypeScript if you do not need it at some point during your development process, for example, to speed up development or if you have new developers working on the project who are not familiar with TypeScript.
Simply remove tsconfig.json file from your project.
This starter kit comes with TailwindCSS support out of the box. TailwindCSS is a utility-first CSS framework that allows you to quickly build custom user interfaces. For more information on how to use TailwindCSS, please refer to the TailwindCSS documentation.
Simply remove the following line:
<link rel="stylesheet" href="{{ STATIC_PATH }}/css/tailwind.css" />
from src/_layouts/base.njk file.
You can also remove tailwindcss section from postcss.config.js and remove tailwind gulp task from gulpfile.js, but it is optional.
Nunjucks is a powerful HTML template engine with a syntax very similar to jinja2. Nunjucks makes easier writing highly-maintainable HTML code.
Nunjucks templates seat in src/_layouts/, src/components/ folders.
To make the most out of Nunjucks, it is recommended to read through its documentation. This will give you a good understanding of its features and how to use them effectively in your project.
You can also read 11ty documentation on templating and data sources.
Another tip for working with Nunjucks is to ensure that your code editor has syntax highlighting for Nunjucks. If your editor does not have native support for Nunjucks, you can set up the syntax highlighting for the Twig template engine instead. This can be done by configuring your editor to use the Twig syntax highlighting when opening .njk files.
11ty has support for many template engines. If you prefer to use a different template engine, you can easily do so.
To do this, you need to replace Nunjucks with your desired template engine in the .eleventy.js file. You can find information on how to configure a different template engine in the 11ty documentation.
This starter kit uses Webpack v5 to build the JavaScript bundle. However, it does not have hot reloading feature enabled, as it is not necessary for static websites.
This template provides the ability to customize the static path for project resources such as images, scripts, styles, etc. For example, you can use a custom CDN URL. Add an .env file to the root directory of the project with the following content STATIC_PATH=http://localhost:9000 then you can reference the STATIC_PATH variable in your code like this <link rel="stylesheet" href="{{ STATIC_PATH }}/css/tailwind.css">
Note: When using STATIC_PATH in Nunjucks macros, it must be passed as props.
This starter kit uses the dotenv package to load environment variables from a .env file. You can add environment variables to the .env file and use them in your code. Additionally, don't forget to include the new variable in the webpack configuration under the EnvironmentPlugin settings. After restarting the project, you will be able to reference the variable within your code like this: process.env.MY_VARIABLE.
If you need to use environment variables in Nunjucks templates, you can add JS files for the variables in src/_data/ folder and then reference them in Nunjucks templates like this: {{ MY_VARIABLE }}. As an example, see the src/_data/STATIC_PATH.js file.
This starter features a convenient way to include SVG files through the use of SVG sprites. By utilizing the gulp-svgstore plugin, it generates a single sprite containing all of your SVG files.
The SVG sprite markup is inlined in base.njk template using {% svg_prite %} shortcode function (there is no need to modify this code).
To show an SVG image on the webpage, first place it in the src/svg folder. For example, if the file is named some-vector.svg.
Then add it to the page in the following way:
<svg><use xlink:href="#icon-some-vector"></use></svg>
Note: some-vector.svg file should be located in the src/svg directory so that gulp-svgstore could add it to the SVG sprite.
You can also use CSS selectors to set properties such as the fill or stroke for this element on the page, without having to edit the SVG file. Additionally, you can even animate specific parts of the SVG element, such as a <path> or <circle>.
You can also take a look at the <svg> examples in the index.njk.
This feature allows you to easily create AVIF and WebP images. It automatically generates multiple sizes for the srcset attribute based on the maximum width specified (the third argument) and the widths defined in the .eleventy.js configuration file.
If you need to add CSS class to <picture> tag then pass it as pictureClass among the options (second argument). To add CSS class to <img> pass class to options argument.
See examples in index.njk to get familiar with {% image %} tag.
This may become a useful approach if you need to display an image instantly on the page without making a request to the server.
<img src="{{ 'src/images/some-image.png' | inline }}" alt="" />
Warning! Please use this feature with caution as it may bloat the final HTML file. Inlining images could be a good approach if the file is quite small, in other cases prefer {% image %} tag.
The postcss-assets plugin allows to inline images into CSS code in Base64 encoding or as is for SVG files:
background: inline('some-image.png')
The plugin also can insert an image sizes:
width: width('some-image.png')
height: height('some-image.png')
background-size: size('some-image.png')
Warning! Use this feature with caution as it may cause the final CSS file to become large. Inlining images is a good option if the file is relatively small, otherwise, it is recommended to use the {% image %} tag instead.
This starter uses twig melody parser to format .njk files with Prettier automatically on each commit. However, there is a known issue when trying to use {% if %} block in a HTML attribute.
For example, the following code would throw a syntax error during the code formatting:
<p class="{% if someExpression %}some-class-name{% endif %}">Some paragraph</p>
To avoid it use {% set %} wrapped in HTML comment (melody parser ignore HTML comments by default) like this:
<!-- {% set someClass = "some-class" if true %} -->
then you can use someClass in the markup like this.
<p class="{{ someClass }}">
Use any other expression instead of true in {% set %} block. You can also use else if you need. This syntax is called if expression in Nunjucks. It is similar to JavaScript ternary or Python one-line if expression.
For example, this text has HTML class attribute (check the code) calculated using an if statement and {% set %} block.
NOTE. If you are still experiencing issues with formatting .njk files, just remove prettier-plugin-twig-nunjucks-melody npm package from your project and .njk files will not be formatted anymore.
For code examples, please refer to src/index.njk.
To see them live, open the index page in the browser by running npm start and going to http://localhost:9000
You can also check them on the live demo page