{"id":24465628,"url":"https://github.com/CosAnca/nucleum","last_synced_at":"2025-10-01T22:31:06.349Z","repository":{"id":20340895,"uuid":"89642140","full_name":"CosAnca/nucleum","owner":"CosAnca","description":"A performance oriented web starter kit","archived":false,"fork":false,"pushed_at":"2023-05-25T14:55:56.000Z","size":4178,"stargazers_count":9,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-06T12:42:58.186Z","etag":null,"topics":["browserslist","browsersync","docker-compose","gulp","gulp-tasks","itcss","performance","postcss","web-starter-kit","webpack4","wordpress"],"latest_commit_sha":null,"homepage":"","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CosAnca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-27T21:33:25.000Z","updated_at":"2022-09-18T12:31:13.000Z","dependencies_parsed_at":"2023-02-18T03:31:32.934Z","dependency_job_id":null,"html_url":"https://github.com/CosAnca/nucleum","commit_stats":null,"previous_names":["cosminanca/fosterkit"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosAnca%2Fnucleum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosAnca%2Fnucleum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosAnca%2Fnucleum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosAnca%2Fnucleum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CosAnca","download_url":"https://codeload.github.com/CosAnca/nucleum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234874633,"owners_count":18900007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browserslist","browsersync","docker-compose","gulp","gulp-tasks","itcss","performance","postcss","web-starter-kit","webpack4","wordpress"],"created_at":"2025-01-21T06:12:18.648Z","updated_at":"2025-10-01T22:31:01.034Z","avatar_url":"https://github.com/CosAnca.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![Nucleum](./src/assets/images/nucleum-banner.png)\n\n**Nucleum** is an opinionated, performance oriented web development starter kit. It can be used as-is as a static site generator, or can be configured and integrated into many different web development environments and sites or apps structures.\n\nThe [extras](./extras) folder contains configuration details for **WordPress** projects. Check the [WordPress with Nucleum](./extras/wordpress/README-WP.md) documentation to learn more about how to set up Nucleum for WordPress based projects.\n\n## Quick start on a fresh project (empty directory)\n\n### Setup\n\nThe easiest way to get started with Nucleum is by using `create-nucleum-project`. This simple CLI tool enables you to quickly start building a new Nucleum project, with everything set up for you. To get started, use the following command:\n\n```zsh\nyarn create nucleum-project\n# or\nnpx create-nucleum-project\n```\n\nAfter the installation is complete, follow the instructions to start the development server. Try editing `src/views/pages/index.njk` and see the result on your browser.\n\nFor more information on how to use `create-nucleum-project`, you can review the [`create-nucleum-project` documentation](https://github.com/CosAnca/create-nucleum-project).\n\n### Manual Setup\n\n**Nucleum** is published as an npm package which allows us to start a new project in a only a few steps:\n\n```zsh\nyarn add nucleum\nyarn nucleum init\n# or\nnpm install nucleum\nnpm run nucleum init\n```\n\nThis will create the default `src` directory and `nucleum.config.js` file in your project directory.\n\nThe `init` command also updates your `package.json` file to include `dev` and `build` scripts for Nucleum:\n\n```js\n// package.json\n\"scripts\": {\n  \"dev\": \"yarn nucleum\",\n  \"build\": \"yarn nucleum build\"\n}\n```\n\nwhich you can then use on the command line:\n\n```zsh\nyarn dev\nyarn build\n# or\nnpm run dev\nnpm run build\n```\n\nA default `browserslist` configuration is added as well into the `package.json` file. You can customize it based on your project needs.\n\n```js\n// package.json\n\"browserslist\": [\n  \"\u003e0.5%\",\n  \"not dead\",\n  \"ie \u003e= 11\",\n  \"not op_mini all\"\n]\n```\n\nYour project's CSS and JavaScript files will be compiled for production to include the necessary prefixes or syntax for the browsers you need to support.\n\nYou can find more details about browserslist and the type of queries its configuration requires by visiting the [browserslist repo](https://github.com/browserslist/browserslist).\n\n## Adding to an existing project?\n\nIf you want to use Nucleum as a front-end build tool in an existing project, you can generate a basic `nucleum.config.js` file with:\n\n```zsh\nyarn nucleum init-config\n# or\nnpm run nucleum init-config\n```\n\nThen edit the configs to match the needs of your project. To understand better how you can customize each config object, take a look at our [`config-defaults`](gulpfile.js/lib/config-defaults.js) file.\n\n## Recommended Setup\n\nTo benefit even further of Nucleum's capabilities, we recommend you install some dev dependencies that can help you lint your SCSS and JavaScript files.\n\nNucleum automatically generates config files for eslint and stylelint that you can either use as they are or change them based on your project needs.\n\n#### Additional dev dependencies\n\n[eslint](https://eslint.org/)\n[eslint-config-prettier](https://github.com/prettier/eslint-config-prettier)\n[eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat)\n[eslint-plugin-prettier](https://github.com/prettier/eslint-plugin-prettier)\n[prettier](https://prettier.io/)\n[stylelint](https://stylelint.io/)\n[stylelint-config-nucleum](https://github.com/CosAnca/stylelint-config-nucleum)\n[husky](https://github.com/typicode/husky)\n[lint-staged](https://github.com/okonet/lint-staged)\n\nYou can install them all at once by running the following command in your Terminal:\n\n```zsh\nyarn add -D eslint eslint-config-prettier eslint-plugin-compat eslint-plugin-prettier husky lint-staged prettier stylelint stylelint-config-nucleum\n# or\nnpm install -D eslint eslint-config-prettier eslint-plugin-compat eslint-plugin-prettier husky lint-staged prettier stylelint stylelint-config-nucleum\n```\n\nIf you'd like to have your code (SCSS and JS) linted before every commit, you can add the following configuraiton objects into your `package.json` file:\n\n```json\n\"husky\": {\n  \"hooks\": {\n    \"pre-commit\": \"lint-staged\"\n  }\n},\n\"lint-staged\": {\n  \"src/assets/js/**/*.js\": [\n    \"eslint --fix\",\n    \"prettier --write\"\n  ],\n  \"src/assets/style/**/*.scss\": [\n    \"stylelint --fix\",\n    \"prettier --write\"\n  ]\n}\n```\n\n# Commands\n\n```zsh\nyarn dev\n# or\nnpm run dev\n```\n\nThis is where the magic happens. The perfect workflow. This runs the development task, which starts compiling, watching, and live updating all our files as we change them. BrowserSync will start a server on port 3000, or do whatever you've configured it to do. You'll be able to see live changes in all connected browsers. Don't forget about the additional BrowserSync tools available on port 3001!\n\n```zsh\nyarn build\n# or\nnpm run build\n```\n\nCompiles files for production to your destination directory. JS files are built using Webpack with standard production optimisations (Uglify, etc.). CSS is run through CSSNano and PurgeCSS. If `rev` is set to `true` in your `nucleum.config.js` file, filenames will be hashed (file.css -\u003e file-a8908d9io20.css) so your server may cache them indefinitely.\n\n# Configuration\n\nYou may override the default configuration by creating a `nucleum.config.js` file. The file will be created by any of the `init` tasks, or you can generate _only_ the config file with the following command:\n\n```zsh\nyarn nucleum init-config\n# or\nnpm run nucleum init-config\n```\n\nBy default, Nucleum expects the config file to live at the root of your project. You may specify an alternative relative location by setting an environment variable:\n\n```js\n// package.json\n\"scripts\": {\n  \"nucleum\": \"NUCLEUM_CONFIG_PATH='./some/location' nucleum\"\n}\n```\n\n```zsh\n# command line\nyarn nucleum\n# or\nnpm run nucleum\n```\n\nThe file must be named `nucleum.config.js`.\n\n### Configuring files structure and tasks\n\n`nucleum.config.js`\n\nThis file specifies the `src` (default to _\"./src\"_) and `dest` (default to _\"./public\"_) root directories under a `basePats` object, and `src` and `dest` for each task, relative to the configured base paths. For example, if your source files live in a folder called `app`, and your compiled files should be output to a folder called `static`, you'd update the base paths `src` and `dest` properties here to reflect that.\n\nThis file also exposes per-task configuration and overrides. At minimum, you just need to set the task to `true` to enable the task with its default configuration. If you wish to configure a task, provide a configuration object instead.\n\n- Any task may be disabled by setting the value to `false`. For example, if your project has its own handling of HTML and template engine (WordPress, Craft, etc), you'll want to set `html` to `false` in your config file.\n- All asset tasks have an `extensions` option that can be used to overwrite the ones that are processed and watched.\n\nSee [config defaults](./gulpfile.js/lib/config-defaults.js) for a closer look. All configuration objects will be merged with these defaults. Note that `array` options are replaced rather than merged or concatenated.\n\n### browserSync\n\nOptions to pass to [browserSync](https://browsersync.io/docs/options).\n\n**If you're using Eleventy (built in) to create a static site**, you'll want to use the `server` property and tell it which directory to serve up via the `baseDir` option.\n\n```js\nbrowserSync: {\n  server: {\n    baseDir: \"public\";\n  }\n}\n```\n\n**If you're running another server (Docker for example)**, you'll want to use the `proxy` option, along with `files` to tell browserSync to watch additional files (like your templates).\n\n```js\nbrowserSync: {\n  proxy: {\n    target: \"localhost\"\n  },\n  files: [\"public/wp-content/themes/nucleum/**/*.php\"]\n}\n```\n\n**If you need to turn on polling within webpack-dev-middleware**, specify `watchOptions` within this section, too.\n\n```js\nbrowserSync: {\n  watchOptions: {\n    poll: true,\n    aggregateTimeout: 300\n  }\n}\n```\n\n**If you need to add extra middlewares**, specify `extraMiddlewares` within the `server` subsection of this section.\n\n```js\nbrowserSync: {\n  server: {\n    extraMiddlewares: [historyApiFallbackMiddleware],\n  },\n},\n```\n\n**If you need to override completely all server's middleware**, specify `middleware` within the `server` subsection of this section.\n\n```js\nbrowserSync: {\n  server: {\n    middleware: [\n      /* On your own! Note that default 'webpack-dev-middleware' will not be enabled using this option */\n    ],\n  },\n}\n```\n\n### javascripts\n\nUnder the hood, JS is compiled with Webpack with a heavily customized Webpack file to get you up and running with little to no configuration. An API for configuring some of the most commonly accessed options are exposed, along with some other helpers for scoping to environment. Additionally, you can get full access to modify Nucleum's `webpackConfig` via the [`customizeWebpackConfig`](#customizeWebpackConfig) option.\n\n#### `src`\n\nThis is the source path, relative to the src base path for the JavaScript files. Default to _\"assets/js\"_.\n\n#### `dest`\n\nThis is the destination path, relative to the dest base path for the compiled JavaScript files. Default to _\"assets/js\"_.\n\n#### `entry` (required)\n\nDiscrete js bundle entry points. A js file will be bundled for each item. Paths are relative to the `js` folder. This maps directly to `webpackConfig.entry`.\n\n#### `publicPath`\n\nThe public path to your assets on your server. Only needed if this differs from the result of `path.join(TASK_CONFIG.basePaths.dest, TASK_CONFIG.javascripts.dest)`. Maps directly to `webpackConfig.publicPath`\n\n#### `devtool`\n\nSets the webpack devtool option in development mode. Defaults to `eval-cheap-module-source-map`, one of the fastest source map options. To enable sourcemaps in production builds, use [`customizeWebpackConfig`](#customizeWebpackConfig).\n\n#### `babel`\n\nObject to overwrite the default Babel loader config object. Set by default to:\n\n```js\npresets: [[\"@babel/preset-env\", { modules: false }]],\nplugins: [\n  [\"@babel/plugin-proposal-class-properties\", { loose: true }],\n  \"@babel/plugin-syntax-dynamic-import\",\n  \"@babel/plugin-transform-runtime\",\n],\n```\n\nSame format as a `.babelrc` file.\n\n#### `babelLoader`\n\nObject to extend the default config for _entire_ Babel loader object. See [Webpack loader documentation](https://webpack.js.org/concepts/loaders/) for details.\n\n#### `provide`\n\nKey value list of variables that should be provided for modules to resolve dependencies on import using [webpack.ProvidePlugin](https://webpack.github.io/docs/list-of-plugins.html#provideplugin). A common example is making jQuery available to all modules (jQuery plugins need this). In that scenario, with `jquery` installed via `yarn`, add this to your javascripts config:\n\n```js\nprovide: {\n  $: \"jquery\",\n  jQuery: \"jquery\"\n}\n```\n\nUnder the hood, this gets passed directly to [webpack.ProvidePlugin](https://webpack.github.io/docs/list-of-plugins.html#provideplugin) in the webpack config.\n\n```js\nplugins: [\n  new webpack.ProvidePlugin({\n    $: \"jquery\",\n    jQuery: \"jquery\",\n  }),\n];\n```\n\n#### `plugins`\n\nDefine additional webpack plugins that should be used in all environments.\n\n#### `loaders`\n\nDefine additional webpack loaders that should be used in all environments. Adds to `webpackConfig.module.rules`\n\n#### `development`, `production`\n\nSpecify additional environment specific configuration to be merged in with Nucleum's defaults\n\n- [`devtool`](https://webpack.js.org/configuration/devtool/#devtool)\n- [`plugins`](https://webpack.js.org/concepts/plugins/)\n- [`loaders`](https://webpack.js.org/concepts/loaders/)\n\n_Production Only:_\n\n- [`definePlugin`](https://webpack.js.org/plugins/define-plugin)\n\n**Example:**\n\n```js\nproduction: {\n  devtool: \"hidden-source-map\",\n  definePlugin: {\n    SOME_API_KEY: \"abcdefg\"\n  },\n  plugins: (webpack) =\u003e { return [ new webpack.IgnorePlugin(/jsdom$/) ] },\n  loaders: [] // Adds to `webpackConfig.module.rules`\n}\n```\n\nBy default, the `env` will be `\"development\"` when running `yarn nucleum`, and `\"production\"` when running `yarn nucleum build`.\n\n#### `hot`\n\nBy default, webpack HMR will simply do a full browser refresh when your js files change. If your code takes advantage of [hot module replacement methods](https://webpack.github.io/docs/hot-module-replacement.html), modules will be hot loaded.\n\n_Defaults to:_\n\n```js\nhot: {\n  enabled: true,\n  reload: true,\n  quiet: true,\n  react: false\n}\n```\n\n**If you're using React** `yarn add react-hot-loader` or `npm install react-hot-loader` and set `react: true` to enable [react-hot-loader](https://github.com/gaearon/react-hot-loader). [Follow the docs](https://github.com/gaearon/react-hot-loader) and update your React app to take advantage. Also install `@babel/preset-react` and add it to the babel presets configuration.\n\n#### `customizeWebpackConfig`\n\nIn the event that an option you need is not exposed, you may access, modify and return a further customized webpackConfig by providing this option as a function. The function will receive the Nucleum `webpackConfig`, `env` and `webpack` as params. The `env` value will be either `development` or `production`.\n\n```js\ncustomizeWebpackConfig: function (webpackConfig, env, webpack) {\n  if(env === \"production\") {\n    webpackConfig.devtool = \"nosources-source-map\"\n  }\n\n  return webpackConfig\n}\n```\n\n**CAUTION!** Avoid overwriting `webpackConfig.entry` or `webpackConfig.plugins` via this function, and rely on the `entry` and `plugins` options above to avoid breaking Nucleum's hot-loading and file revisioning setup ([view source](./gulpfile.js/lib/webpack-multi-config.js)).\n\n### stylesheets\n\n#### `src`\n\nThis is the source path, relative to the src base path for the Sass files. Default to _\"assets/styles\"_.\n\n#### `dest`\n\nThis is the destination path, relative to the dest base path for the compiled CSS files. Default to _\"assets/css\"_.\n\n#### `presetEnv`\n\n[PostCSS Preset Env](https://github.com/csstools/postcss-preset-env) lets you convert modern CSS into something most browsers can understand, determining the polyfills you need based on your targeted browsers or runtime environments.\n\nBe default we set the stage of postcssPresetEnv to 0 which will enable experimental feature of CSS.\n\nWithin this object you can also override the `browserslist` configuration and/or `autoprefixer` settings. Please read more about postcssPresetEnv configuration on their repo page https://github.com/csstools/postcss-preset-env#options.\n\n```js\nstylesheets: {\n  presetEnv: {\n    stage: 3,\n    browsers: \"last 2 versions\",\n    autoprefixer: { grid: true } // passing `autoprefixer: false` disables autoprefixer\n  }\n}\n```\n\n#### `normalize`\n\n[PostCSS Normalize](https://github.com/csstools/postcss-normalize) lets you use the parts of normalize.css you need from your `browserslist`. Please read more about postcssNormalize configuration option on their repo page https://github.com/csstools/postcss-normalize#options.\nBy default this option is disabled in Nucleum but you can enable it either by setting the `forceImport` option to `true` under `stylesheets.normalize` object in `nucleum.config.js` without having to specifically include the library at the beginning of our sass file, or by importing the library in your main sass file.\n\n#### `cssnano`\n\n[cssnano](https://cssnano.co/) takes your nicely formatted CSS and runs it through many focused optimisations, to ensure that the final result is as small as possible for a production environment. _This optimisation is only run on the build task_.\n\n#### `purgecss`\n\n[purgecss](https://www.purgecss.com/) is a tool to remove unused CSS. Purgecss has a list of options that allow you to customize its behavior. Customization can improve the performance and efficiency of Purgecss. You can customize its configuration with the options found on their documentation page https://www.purgecss.com/configuration. _This optimisation (when enabled) will only run on the build task_.\n\n```js\nstylesheets: {\n  purgecss: {\n    content: [\"./src/**/*.njk\"], // the path should be absolute (you may need to use `path.resolve()`)\n    // extra configuration (check the options in their documentation)\n  }\n}\n```\n\n**IMPORTANT** All of the above stylesheets options are included as PostCSS plugins.\n\n#### `postcssPlugins`\n\nAllows passing extra postcss plugins into the pipeline.\n\n```js\nstylesheets: {\n  postcssPlugins: [pluginName(pluginConfig)];\n}\n```\n\n#### `sass`\n\nOptions to pass to [node-sass](https://github.com/sass/node-sass#options).\n\nDefaults to `{ includePaths: [\"./node_modules\"] }` so you can `@import` files installed to `node_modules`.\n\n#### `criticalCss`\n\nWe use [critical](https://github.com/addyosmani/critical) to extract and inline critical-path (above-the-fold) CSS from HTML.\n\n**IMPORTANT** Use the `criticalCss` object inside `nucleum.config.js` file to set the critical `src` and `dest`. _Setting these properties inside `criticalCss.config` will not work_.\n\nThere are two ways of generating critical CSS.\n\n1. Running the gulp task through all the templates generated at the root of the public folder.\n\n```js\n// nucleum.config.js\ncriticalCss: {\n  src: \"./**/*.html\",\n  dest: \"./\",\n  config: {\n    base: \"./public\",\n    inline: true,\n    width: 1280,\n    height: 800,\n  },\n}\n```\n\n1. Creating a `pages` array where each page object sets an `url` and a `template` property. This is useful for generating critical CSS when the templates are generated by CMSs or other tools.\n\n```js\n// nucleum.config.js\ncriticalCss: {\n  src: \"\", // this should be empty because the src is set per page in the `pages` array\n  dest: \"assets/style/critical\",\n  siteUrl: \"http://localhost\", // can also be external URL\n  config: {\n    // ...critical options\n    base: \"./public/wp-content/themes/nucleum\",\n    width: 1200,\n    height: 1200\n  },\n  pages: [\n    {\n      url: \"\",\n      template: \"index\"\n    }\n  ]\n}\n```\n\n**IMPORTANT** If `pages.url` is not set to a `.html` file or to a file system path make sure your website is running on a local server for the criticalCss task to work.\n\nSetting the `config` object, you can create the necessary configuration for [critical](https://github.com/addyosmani/critical).\n\n### html\n\n#### `src`\n\nThis is the source path, relative to the src base path for the template languages files. Default to _\"views\"_.\n\n#### `dest`\n\nThis is the destination path, relative to the dest base path for the compiled template files. Default to _\"./\"_.\n\n**Note:** If you are on a platform that's already handling html, like a CMS (WordPress, Craft, etc.), set `html: false` or delete the configuration object completely from `nucleum.config.js`. If that's the case, don't forget to use the BrowserSync [`files` option](https://browsersync.io/docs/options#option-file) in the `browserSync` config object to start watching your templates folder.\n\nNucleum is using [Eleventy] under the hood to generate static HTML files.\n\nWe use [Nunjucks] as the default templating engine but you can change that to any other Eleventy [supported template languages](https://www.11ty.dev/docs/languages/). Also, by default the HTML output is beautified rather than minified. If you'd like to change that behaviour, you'll have to add a new transform to minify the output. Find out more in the [Eleventy Documentation](https://www.11ty.dev/docs/config/#transforms-example-minify-html-output).\n\nYou can change or extend Eleventy's configuration through the [.eleventy.js](./.eleventy.js) file.\n\n**IMPORTANT** If you change the html src and dest paths make sure the paths under the dir object in .eleventy.js file are updated accordingly.\n\nIf you ever need a more verbose error output for Eleventy, run your project with the following command: `DEBUG=Eleventy* yarn dev`.\n\n### static\n\nThere are some files that belong in your root destination directory that you won't want to process or revision in production. Things like [favicons, app icons, etc.](http://realfavicongenerator.net), should go in `src/static`, and will get copied over to `public` as a last step (after revisioning in production). _Nothing_ should ever go directly in `public`, since it gets completely trashed and re-build when running the `default` or `production` tasks.\n\n#### `scrOptions`\n\nOptions passed to `gulp.src`. See [gulp documentation](https://github.com/gulpjs/gulp/blob/master/docs/API.md#options) for details. Defaults to:\n\n```js\nstatic: {\n  srcOptions: {\n    dot: true; // include dotfiles\n  }\n}\n```\n\n### fonts, images\n\n#### `src`\n\nThis is the source path, relative to the src base path for the fonts or images files. Default to _\"assets/fonts\"_ and _\"assets/fonts\"_.\n\n#### `dest`\n\nThis is the destination path, relative to the dest base path for the fonts or images files. Default to _\"assets/images\"_ and _\"assets/images\"_.\n\nThese tasks simply copy files from `src` to `dest` configured in `nucleum.config.js`. Nothing to configure here other that specifying extensions or disabling the task.\n\n### icons\n\n#### `src`\n\nThis is the source path, relative to the src base path for the icon files. Default to _\"assets/icons\"_.\n\n#### `dest`\n\nThis is the destination path, relative to the dest base path for the compiled SVG sprite file. Default to _\"assets/images\"_.\n\nGenerates an SVG Sprite from `.svg` files in `src/icons`. You can either include the created SVG directly on the page and reference the icon by id like this:\n\n```html\n\u003csvg viewBox=\"0 0 1 1\"\u003e\u003cuse xlink:href=\"#my-icon\"\u003e\u003c/use\u003e\u003c/svg\u003e\n```\n\nor reference the image remotely:\n\n```html\n\u003csvg viewBox=\"0 0 1 1\"\u003e\n  \u003cuse xlink:href=\"/assets/images/icons.svg#my-icon\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\nIf you reference the sprite remotely, be sure to include something like [inline-svg-sprite](https://github.com/vigetlabs/inline-svg-sprite) to ensure external loading works on Internet Explorer.\n\nNucleum includes a macro inside `src/includes/_macros.njk` which generates the required svg markup for your icons, so you can just do:\n\n```njk\n{% from \"_macros.njk\" import icon %}\n\n{{ icon(\"my-icon\") }}\n```\n\nWhich outputs:\n\n```html\n\u003csvg class=\"c-icon\"\u003e\n  \u003cuse xlink:href=\"/assets/images/icons.svg#my-icon\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\nFor advanced usage, see the example at the top of the `src/includes/_macros.njk` file.\n\nThis particular setup allows styling 2 different colors from your CSS. You can have unlimited colors hard coded into your svg.\n\nIn the following example, the first path will be `red`, the second will be `white`, and the third will be `blue`. Paths **without a fill attribute** will inherit the `fill` property from CSS. Paths with `fill=\"currentColor\"` will inherit the current CSS `color` value, and hard-coded fills will not be overwritten, since inline styles trump CSS values.\n\n```scss\n.c-icon {\n  fill: #f00;\n  color: #fff;\n}\n```\n\n```svg\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\"\u003e\n  \u003cpath d=\"...\"/\u003e\n  \u003cpath fill=\"currentColor\" d=\"...\"/\u003e\n  \u003cpath fill=\"blue\" d=\"...\"/\u003e\n\u003c/svg\u003e\n```\n\nMake sure:\n\n1. you draw your SVGs on a square (24 x 24) canvas\n2. you center your artwork\n3. you expand/combine any shapes of the same color\n\nThe last step is very important to ensure the correct style (fill) gets applied to the path you actually target.\n\nWe also include [postcss-svg](https://github.com/jonathantneal/postcss-svg) which automatically encodes SVGs referenced through `url(\"../path/to/file.svg\")` in our CSS files.\n\nExample:\n\n```scss\n.c-element {\n  background-image: url(\"../img/logo.svg\");\n}\n```\n\nThe above will output:\n\n```css\n.c-element {\n  background-image: url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' ...\");\n}\n```\n\nWe can also set the fill color of the encoded SVG using custom properties in our SVGs markup.\n\nTo use this option make sure the `\u003cpath/\u003e` styles are not set with individual attributes (like `fill=\"currentColor\"` or `fill=\"red\"`) but within a single `style` attribute, like so:\n\n```svg\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\"\u003e\n  \u003cpath style=\"fill: currentColor; fill: var(--icon-fill-color, currentColor)\" d=\"M7 7h2v5H7V7zm1-1a1 1 0 1 1 0-2 1 1 0 0 1 0 2zm0 8A6 6 0 1 0 8 2a6 6 0 0 0 0 12zm0 2A8 8 0 1 1 8 0a8 8 0 0 1 0 16z\"/\u003e\n\u003c/svg\u003e\n\n```\n\nThe first `fill` property is a fallback for Internet Explorer while the second one is picked up by browsers that support CSS Custom Properties (CSS Variables).\n\nIn our SCSS file, when we need an inline icon we can just reference the symbol id from the SVG sprite or the SVG file path, like this:\n\n```scss\n.c-icon {\n  background-image: url(\"icons#icon-info\"param(--icon-fill-color color(\"success\")));\n}\n```\n\n### clean\n\n```js\nclean: {\n  patterns: [\n    path.resolve(process.env.INIT_CWD, \"dist/assets\"),\n    path.resolve(process.env.INIT_CWD, \"dist/templates\"),\n  ];\n}\n```\n\nBy default, the entire `dest` directory is deleted before each build. By setting the `clean.patterns` option, you can specify which directory or directories (using globbing syntax) should be deleted instead. Use this if you have subdirectories within the `dest` directory that should be left alone (media uploaded through a CMS, say).\n\n### production\n\nFilenames are revisioned when running the production `build` task. If you want to disable this behaviour, you can set `rev` to false.\n\n```js\nproduction: {\n  rev: true;\n}\n```\n\nThe default directory where the `rev-manifest.json` file is generated is `assets`. If you want to output your compiled files into a different directory, you can also ensure the `rev-manifest.json` file is generated as part of the same directory by using the `manifestDir` property.\n\nFor example, in a project where you only need to handle the CSS and JS compilation and bundling and in your `nucleum.config.js` file you set the `dist` path directly to your assets destination folder, you can set the `manifestDir` to an empty string.\n\n```js\nproduction: {\n  rev: {\n    manifestDir: \"\";\n  }\n}\n```\n\n### additionalTasks\n\nIf you wish to define additional gulp tasks, and have them run at a certain point in the build process, you may use this configuration to do so via the following config object:\n\n```js\nadditionalTasks: {\n  initialize(gulp, TASK_CONFIG) {\n    // Add gulp tasks here\n  },\n  development: {\n    prebuild: [],\n    postbuild: []\n  },\n  production: {\n    prebuild: [],\n    postbuild: []\n  }\n}\n```\n\nNucleum will call `initialize`, passing in `gulp`, along with the path and task configs. Use this method to define or `require` additional gulp tasks. You can specify when and in what order your custom tasks should run in the `production` and `development` `prebuild` and `postbuild` options.\n\nFor example, say you had a sprite task you wanted to run before your css compiled, and in production, you wanted to run an image compression task you had after all assets had been compiled. Your configuration might look something like this:\n\n```js\nadditionalTasks: {\n  initialize(gulp, TASK_CONFIG) {\n    gulp.task(\"createPngSprite\", function() {\n      // do stuff\n    })\n    gulp.task(\"compressImages\", function() {\n      // compress all the things\n    })\n  },\n  development: {\n    prebuild: [\"createPngSprite\"],\n    postbuild: []\n  },\n  production: {\n    prebuild: [\"createPngSprite\"],\n    postbuild: [\"compressImages\"]\n  }\n}\n```\n\n# FAQ\n\n## Can I customize and add Gulp tasks?\n\nYep! See [additionalTasks](#additionaltasks).\n\nYou can also clone this repo, copy over the gulpfile.js folder and package.json dependencies and run `gulp` instead of installing it as a modules directly, or you could fork and maintain your own custom setup.\n\n## I don't see JS files in my dest directory during development\n\nJS files are compiled and live-update via BrowserSync + WebpackDevMiddleware + WebpackHotMiddleware. That means, that you won't actually see `.js` files output to your destination directory during development, but they will be available to your browser running on the BrowserSync port.\n\n## What's under the hood?\n\nGulp tasks! Built combining the following:\n\n| Feature               | Packages Used                                                     |\n| --------------------- | ----------------------------------------------------------------- |\n| **HTML**              | [Eleventy]                                                        |\n| **CSS**               | [Sass], [PostCSS], [purgecss], [cssnano]                          |\n| **JavaScript**        | [Babel], [babel-preset-env], [Webpack]                            |\n| **Icons**             | Auto-generated SVG Sprites with [svgstore]                        |\n| **Live Updating**     | [BrowserSync], [Webpack Dev Middleware], [Webpack Hot Middleware] |\n| **Production Builds** | [Filename hashing], [Size Report]                                 |\n\nExtras:\n\n| Feature            | Packages Used                                                                        |\n| ------------------ | ------------------------------------------------------------------------------------ |\n| **WordPress**      | [Docker], [docker-compose], [WordPress quick start](./extras/wordpress/README-WP.md) |\n| **Sass Libraries** | [Bourbon](http://bourbon.io/), [Adaptable](https://github.com/CosAnca/adaptable/)    |\n\n[sass]: https://sass-lang.com\n[libsass]: https://sass-lang.com/libsass\n[node-sass]: https://github.com/sass/node-sass\n[postcss]: https://github.com/postcss/postcss\n[postcss-preset-env]: https://github.com/csstools/postcss-preset-env\n[postcss-normalize]: https://github.com/csstools/postcss-normalize\n[postcsssvg]: https://github.com/jonathantneal/postcss-svg\n[purgecss]: https://github.com/FullHuman/purgecss\n[cssnano]: https://github.com/cssnano/cssnano\n[babel]: https://babeljs.io/\n[babel-preset-env]: https://babeljs.io/docs/en/babel-preset-env\n[webpack]: https://webpack.js.org/\n[webpack dev middleware]: https://github.com/webpack/webpack-dev-middleware\n[webpack hot middleware]: https://github.com/glenjamin/webpack-hot-middleware\n[eleventy]: https://11ty.dev\n[svgstore]: https://github.com/w0rm/gulp-svgstore\n[browsersync]: https://www.browsersync.io/\n[docker]: https://www.docker.com/products/docker-desktop\n[docker-compose]: https://docs.docker.com/compose/install/#install-compose\n[filename hashing]: https://github.com/sindresorhus/gulp-rev\n[size report]: https://github.com/jaysalvat/gulp-sizereport\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCosAnca%2Fnucleum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCosAnca%2Fnucleum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCosAnca%2Fnucleum/lists"}