{"id":15011185,"url":"https://github.com/brocessing/kirby-webpack","last_synced_at":"2025-04-09T19:04:27.106Z","repository":{"id":54541864,"uuid":"83082357","full_name":"brocessing/kirby-webpack","owner":"brocessing","description":":muscle: A Kirby CMS starter-kit with modern frontend tools","archived":false,"fork":false,"pushed_at":"2021-02-20T17:26:15.000Z","size":535,"stargazers_count":180,"open_issues_count":11,"forks_count":23,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-23T21:01:37.510Z","etag":null,"topics":["boilerplate","browsersync","es6","getkirby","hmr","kirby","kirby-cms","less","livereload","php","preprocessor","sass","stylus","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/brocessing.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-02-24T21:01:57.000Z","updated_at":"2025-02-25T12:57:11.000Z","dependencies_parsed_at":"2022-08-13T19:10:32.422Z","dependency_job_id":null,"html_url":"https://github.com/brocessing/kirby-webpack","commit_stats":null,"previous_names":[],"tags_count":19,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brocessing%2Fkirby-webpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brocessing%2Fkirby-webpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brocessing%2Fkirby-webpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brocessing%2Fkirby-webpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brocessing","download_url":"https://codeload.github.com/brocessing/kirby-webpack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248095017,"owners_count":21046770,"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":["boilerplate","browsersync","es6","getkirby","hmr","kirby","kirby-cms","less","livereload","php","preprocessor","sass","stylus","webpack"],"created_at":"2024-09-24T19:39:36.599Z","updated_at":"2025-04-09T19:04:27.064Z","avatar_url":"https://github.com/brocessing.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/brocessing/kirby-webpack/assets/kirbywebpack-logo.png\" width=\"100\" height=\"auto\" alt=\"logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ekirby-webpack\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eA Kirby 3 starter-kit with modern frontend tools\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- License --\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/brocessing/kirby-webpack/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003e NOTE : This starter-kit is for **Kirby 3**. For the Kirby 2 version of this starter-kit, [check this branch](https://github.com/brocessing/kirby-webpack/tree/kirby-2).\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n## Table of Content\n- [About](#about)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Project structure](#project-structure)\n- [Working with Kirby-webpack](#working-with-kirby-webpack)\n  * [Webpack](#webpack)\n  * [Kirby](#kirby)\n  * [Kirby Package Manager](#kirby-package-manager)\n- [List of Kirby-webpack commands](#list-of-kirby-webpack-commands)\n- [Want a custom starter kit ?](#want-a-custom-starter-kit-)\n  * [`main.config.js`](#mainconfigjs)\n  * [`kirby.config.json`](#kirbyconfigjson)\n- [Contribute](#contribute)\n- [License](#license)\n\n\u003cbr\u003e\u003cbr\u003e\n\n## About\n\n\u003e Kirby is a file-based CMS. Easy to setup. Easy to use. Flexible as hell.\n\nBut it lacks the frontend tools ; especially if you're more a front than a back developper.  \nKirby-webpack wraps PHP and [Kirby CMS](http://getkirby.com) inside a full pre-configured [npm](npmjs.com) + [Webpack](https://webpack.github.io/) environnement.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Features\n\n- No more trouble with git submodules: introducing our own **Kirby Package Manager**\n- [Browsersync](https://browsersync.io/) dev server with **livereload** on all your website files\n- **Built-in PHP Server** wrapped in the dev server - we handle PHP for you\n- [Webpack 4](https://webpack.github.io/) with [HMR](https://webpack.github.io/docs/hot-module-replacement.html) \n- [SASS](https://sass-lang.com/) + [PostCSS](http://postcss.org/)  + [Autoprefixer](https://github.com/postcss/autoprefixer) \n- Option to **automatically switch from [SASS](https://sass-lang.com/) to [LESS](http://lesscss.org/) or [Stylus](http://stylus-lang.com/)**\n- **`ES6`** transpilation with [babel](https://babeljs.io/) + [babel-preset-env](https://github.com/babel/babel-preset-env)\n- Linting with [ESLint](https://eslint.org/) and the [Standard](http://standardjs.com/) presets\n- Generate a `stats.json` file from your bundled js to optimize your dependency tree\n- **Multiple config files** to make your own workflow from the starterkit\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Requirements\n- `node` \u003e= 8\n- `npm` \u003e= 5\n- `php` \u003e= 5.4\n  - macOS → `php` command is native. you don't have to do anything!\n  - windows → install it via the official PHP website: [http://windows.php.net/download/](http://windows.php.net/download/)\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Installation\n\n##### Clone the starterkit and install its dependencies\n\u003e`npm install` will also trigger the **Kirby Package Manager** : Kirby core, panel and plugins will be automatically installed right after an npm installation.\n\n```sh\n$ git clone https://github.com/brocessing/kirby-webpack my-project\n$ cd my-project\n$ npm install\n```\n\n##### :bulb: Before starting your project, it is recommanded to unboil it using [brocessing/`unboil`](https://github.com/brocessing/unboil) :\n\u003e`unboil` allows you to clean a boilerplate project (files like package.json, readme, git...) to quickly start your own project from it.\n\n```sh\n$ npm i -g unboil # install unboil globally\n$ cd my-project\n$ unboil          # use it on your brand new kirby-webpack installation\n```\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Project structure\n\n\n```sh\nkirby-webpack/\n│\n├── scripts/\n│   # built-in scripts used by Kirby-webpack\n│\n├── src/           \n│   # JS \u0026 Less/Sass/Stylus sources to be bundled by Webpack\n│\n├── www/               \n│   # your usual Kirby website folder\n│   # this is all you need to deploy to your server\n│   │\n│   ├── assets/\n│   ├── content/\n│   ├── site/\n│   └── ...\n│\n├── kirby.config.json\n├── main.config.js\n└── package.json\n```\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Working with Kirby-webpack\n\n### Webpack\nUsing Webpack means that you can now have source files and dependencies for all your `JS` and `CSS` assets.\n\nThe right way to use Kirby-webpack is to **code all your javascript and LESS (or Sass, or Stylus) files in the [`src/`](src) folder**. On `npm run build`, Webpack will analyze, compile and bundle all your sources into the main [`www/`](www) Kirby folder.\n\nThat means that [`www/`](www) is the only folder you have to deploy to your server.\n\n\u003eNote: you can totally use Kirby as usual by creating your `js` and/or `css` files into [`www/assets/`](www/assets), but you will not benefit from Webpack compilation nor auto-injection. You will however still have livereload capability.\n\n#### Relative urls in CSS sourcefiles\n:warning: If you use relative url in your sass/stylus/less, you had to write them **relative to the output of the bundled css file**, not the source filepath.\n\n###### Example\n```css\n/**\n * Your less source file is 'src/index.less'\n * It will be bundle to 'www/assets/bundle.css'\n * You want to require 'www/assets/images/logo.png' in your less file.\n */\n\n/* GOOD: logo.png is relative to your bundle.css filepath */\nbody { background: url('images/logo.png'); }\n\n/* WRONG: logo.png doesn't have to be relative to your website root */\nbody { background: url('assets/images/logo.png'); }\n\n/* WRONG: logo.png doesn't have to be relative to the source file */\nbody { background: url('../www/assets/images/logo.png'); }\n```\n\n\u003cbr\u003e\n\n### Kirby\n_Kirby-webpack try to be as least intrusive as possible. That said, there is some minor modifications to your ordinary Kirby config you need to be aware of :_\n\n#### The `kirby-webpack` plugin\nThere is a special [`kirby-webpack`](www/site/plugins/kirby-webpack) Kirby plugin containing all required helpers to make Kirby-webpack working correctly. Don't remove it!\n\n#### CSS livereload \n\n\u003e Use **`liveCSS()`** instead of the usual `css()` to enable the CSS hot-reloading.  \nContinue to use `css()` for simple vendor CSS files which don't require hot-reloading.\n\n```diff  \n\u003c?php\n-   echo css('assets/bundle.css')\n+   echo liveCSS('assets/bundle.css')\n?\u003e\n```\n\n#### Changes to `config.localhost.php`\n\u003e These lines are required in [`config.localhost.php`](www/site/config/config.localhost.php) for the dev server to work.\n\n\u003e If you configure kirby-webpack to work with a proxy and a vhost, you will have to rename [`config.localhost.php`](www/site/config/config.localhost.php) accordingly to the virtual-host you use.\n\n```php\n  if (isset($_SERVER['HTTP_X_FORWARDED_FOR']) \u0026\u0026 $_SERVER['HTTP_X_FORWARDED_FOR'] === 'webpack') {\n    c::set('url', '//' . $_SERVER['HTTP_X_FORWARDED_HOST']);\n  }\n```\n\n#### Bonus: know if Webpack is being used\n```php\nif (isWebpack()) {\n  echo 'Your are viewing the site through the dev server.';\n}\n```\n\n\u003cbr\u003e\n\n### Kirby Package Manager\nKeeping a Kirby starterkit up-to-date can quickly become tedious, especially if you have a lot of plugins. Working with git submodules may seem like a good idea, but is usually not, as it tends to make your git history harder to keep clean.\n\nRather than using [Kirby CLI](https://github.com/getkirby/cli/), Kirby-webpack comes with its own _npm flavored_ **Kirby Package Manager**, allowing for a cleaner way to work both in the NodeJS and in the Git environment.\n\n**Kirby Package Manager** works by keeping a list of all installed Kirby plugins in [`kirby.config.json`](kirby.config.json). Run `npm run kirby:add` to download and register a plugin, and `npm run kirby:remove` to remove and unregister one.  \n\nThe registered plugins will be added to [`.gitignore`](.gitignore), and updated each time you'll run `npm install` or `npm run kirby:update`.\n\n\u003e Note: you can also manually edit [`kirby.config.json`](kirby.config.json) as described in \"**[Want a custom starter kit ?](#kirbyconfigjson)**\".  \n\n\u003cp\u003e\u003c/p\u003e\n\n\u003e Note: you can still manually download and install plugins the old way, but **Kirby Package Manager** won't be able to track them.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## List of Kirby-webpack commands\n\n### Main\n- `npm install`\n\u003eInstall all npm dependencies, then install all Kirby-webpack dependencies. Please note that the `postinstall` script automatically installs the Kirby core registered in [`kirby.config.json`](kirby.config.json).\n\n- `npm run start`\n\u003eStart the PHP dev server with livereload on all your Kirby-webpack files.\n\n- `npm run build`\n\u003eBuild your `js` and `scss`/`less`/`styl` source files, and bundle them in the [`www/`](www) folder.\n\n### Kirby Package Manager\n\n- `npm run kirby:update`\n\u003e Update Kirby core, panel and all the plugins registered in [`kirby.config.json`](kirby.config.json).\n\n- `npm run kirby:ls`\n\u003eList all the Kirby modules registered in [`kirby.config.json`](kirby.config.json).\n\n- `npm run kirby:add`\n\u003eRun an interactive shell that allows you to add new Kirby plugin to your Kirby-webpack setup.\n\n- `npm run kirby:remove`\n\u003eRun an interactive shell that allows you to remove a Kirby plugin from your Kirby-webpack setup.\n\n### Additional tools\n- `npm run stats`\n\u003eGenerate a `stats.json` of your bundled `js` to analyze your dependency tree.\n\n- `npm run lint`\n\u003eLint your `js` files using [ESLint](https://eslint.org/) and the [Standard](http://standardjs.com/) presets.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Want a custom starter kit ?\n\n**Fork** this repository and build your own starter kit inside [`www/`](www).  \nEdit [`main.config.js`](main.config.js) and [`kirby.config.json`](kirby.config.json) to customize your Kirby-webpack configuration.\n\n\u003cbr\u003e\n\n### `main.config.js`\nEdit [`main.config.js`](main.config.js) to define your favorite CSS preprocessor, dev server options, and to customize your project folder architecture.  \n\u003e Note: Kirby-webpack will automatically update your npm packages to match the CSS preprocessor you defined in [`main.config.js`](main.config.js).\n\n\u003cbr\u003e\n\n### `kirby.config.json`\n\nEdit [`kirby.config.json`](kirby.config.json) to register your favorite Kirby plugins, and Kirby-webpack will automagically install and update them for you.  \n\nAlternatively, use `npm run kirby:add` to add plugins via an interactive shell.\n\n```json\n{\n  \"modules\": {\n    \"core\": \"https://github.com/getkirby/kirby.git\",\n    \"plugins\": {\n      \"kirby-color\": \"https://github.com/TimOetting/kirby-color.git\"\n    }\n  }\n}\n```\n\u003e Note: the left-hand value corresponds to the name of the plugin, not the name of its git repository.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Contribute\n\n### Issues \nFeel free to submit any issue or request.\n\n### Pull Request\n1. **Fork** the repo on GitHub\n2. **Clone** the project to your own machine\n3. **Commit** changes to your own branch\n4. **Push** your work back up to your fork\n5. Submit a **Pull request** so that we review your changes\n\n\u003csup\u003eBe sure to merge the latest from `upstream` before making a pull request.\u003c/sup\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n## License\n[MIT.](https://tldrlegal.com/license/mit-license)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrocessing%2Fkirby-webpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrocessing%2Fkirby-webpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrocessing%2Fkirby-webpack/lists"}