- About
- Features
- Requirements
- Installation
- Project structure
- Working with Kirby-webpack
- List of Kirby-webpack commands
- Want a custom starter kit ?
- Contribute
- License
Kirby is a file-based CMS. Easy to setup. Easy to use. Flexible as hell.
But it lacks the frontend tools ; especially if you're more a front than a back developper.
Kirby-webpack wraps PHP and Kirby CMS inside a full pre-configured npm + Webpack environnement.
- No more trouble with git submodules: introducing our own Kirby Package Manager
- Browsersync dev server with livereload on all your website files
- Built-in PHP Server wrapped in the dev server - we handle PHP for you
- Webpack 4 with HMR
- LESS + PostCSS + Autoprefixer
- Option to automatically switch from LESS to SASS or Stylus
ES6
transpilation with babel + babel-preset-env- Linting with ESLint and the Standard presets
- Generate a
stats.json
file from your bundled js to optimize your dependency tree - Multiple config files to make your own workflow from the starterkit
node
>= 8npm
>= 5php
>= 5.4- macOS →
php
command is native. you don't have to do anything! - windows → install it via the official PHP website: http://windows.php.net/download/
- macOS →
npm install
will also trigger the Kirby Package Manager : Kirby core, panel and plugins will be automatically installed right after an npm installation.
$ git clone https://github.com/brocessing/kirby-webpack my-project
$ cd my-project
$ npm install
💡 Before starting your project, it is recommanded to unboil it using brocessing/unboil
:
unboil
allows you to clean a boilerplate project (files like package.json, readme, git...) to quickly start your own project from it.
$ npm i -g unboil # install unboil globally
$ cd my-project
$ unboil # use it on your brand new kirby-webpack installation
kirby-webpack/
│
├── scripts/
│ # built-in scripts used by Kirby-webpack
│
├── src/
│ # JS & Less/Sass/Stylus sources to be bundled by Webpack
│
├── www/
│ # your usual Kirby website folder
│ # this is all you need to deploy to your server
│ │
│ ├── assets/
│ ├── content/
│ ├── site/
│ └── ...
│
├── kirby.config.json
├── main.config.js
└── package.json
Using Webpack means that you can now have source files and dependencies for all your JS
and CSS
assets.
The right way to use Kirby-webpack is to code all your javascript and LESS (or Sass, or Stylus) files in the src/
folder. On npm run build
, Webpack will analyze, compile and bundle all your sources into the main www/
Kirby folder.
That means that www/
is the only folder you have to deploy to your server.
Note: you can totally use Kirby as usual by creating your
js
and/orcss
files intowww/assets/
, but you will not benefit from Webpack compilation nor auto-injection. You will however still have livereload capability.
/**
* Your less source file is 'src/index.less'
* It will be bundle to 'www/assets/bundle.css'
* You want to require 'www/assets/images/logo.png' in your less file.
*/
/* GOOD: logo.png is relative to your bundle.css filepath */
body { background: url('images/logo.png'); }
/* WRONG: logo.png doesn't have to be relative to your website root */
body { background: url('assets/images/logo.png'); }
/* WRONG: logo.png doesn't have to be relative to the source file */
body { background: url('../www/assets/images/logo.png'); }
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 :
There is a special kirby-webpack
Kirby plugin containing all required helpers to make Kirby-webpack working correctly. Don't remove it!
Use
liveCSS()
instead of the usualcss()
to enable the CSS hot-reloading.
Continue to usecss()
for simple vendor CSS files which don't require hot-reloading.
<?php
- echo css('assets/bundle.css')
+ echo liveCSS('assets/bundle.css')
?>
Kirby's license key registration has been moved into its own config/license.php
file.
This file is git ignored, and required in config.php
. That way you can enter a license key without fear to go public when using Git.
In a multi-environement setup, require
license.php
in all revelant config files.
@include __DIR__ . DS . 'license.php';
Thanks to Malvese for the idea.
These lines are required in
config.localhost.php
for the dev server to work.
If you configure kirby-webpack to work with a proxy and a vhost, you will have to rename
config.localhost.php
accordingly to the virtual-host you use.
if (isset($_SERVER['HTTP_X_FORWARDED_FOR']) && $_SERVER['HTTP_X_FORWARDED_FOR'] === 'webpack') {
c::set('url', '//' . $_SERVER['HTTP_X_FORWARDED_HOST']);
}
if (isWebpack()) {
echo 'Your are viewing the site through the dev server.';
}
Keeping 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.
Rather than using Kirby 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.
Kirby Package Manager works by keeping a list of all installed Kirby plugins in kirby.config.json
. Run npm run kirby:add
to download and register a plugin, and npm run kirby:remove
to remove and unregister one.
The registered plugins will be added to .gitignore
, and updated each time you'll run npm install
or npm run kirby:update
.
Note: you can also manually edit
kirby.config.json
as described in "Want a custom starter kit ?".
Note: you can still manually download and install plugins the old way, but Kirby Package Manager won't be able to track them.
npm install
Install all npm dependencies, then install all Kirby-webpack dependencies.
npm run start
Start the PHP dev server with livereload on all your Kirby-webpack files.
npm run build
Build your
js
andscss
/less
/styl
source files, and bundle them in thewww/
folder.
npm run kirby:update
Update Kirby core, panel and all the plugins registered in
kirby.config.json
.
npm run kirby:ls
List all the Kirby modules registered in
kirby.config.json
.
npm run kirby:add
Run an interactive shell that allows you to add new Kirby plugin to your Kirby-webpack setup.
npm run kirby:remove
Run an interactive shell that allows you to remove a Kirby plugin from your Kirby-webpack setup.
npm run stats
Generate a
stats.json
of your bundledjs
to analyze your dependency tree.
npm run lint
Fork this repository and build your own starter kit inside www/
.
Edit main.config.js
and kirby.config.json
to customize your Kirby-webpack configuration.
Edit main.config.js
to define your favorite CSS preprocessor, dev server options, and to customize your project folder architecture.
Note: Kirby-webpack will automatically update your npm packages to match the CSS preprocessor you defined in
main.config.js
.
Edit kirby.config.json
to register your favorite Kirby plugins, and Kirby-webpack will automagically install and update them for you.
Alternatively, use npm run kirby:add
to add plugins via an interactive shell.
{
"modules": {
"core": "https://github.com/getkirby/kirby.git",
"panel": "https://github.com/getkirby/panel.git",
"fields": {
"markdown": "https://github.com/JonasDoebertin/kirby-visual-markdown"
},
"plugins": {},
"tags": {},
"widgets": {}
}
}
Note: the left-hand value corresponds to the name of the plugin, not the name of its git repository. For instance, kirby-visual-markdown is named
markdown
, and needs to be in a folder namedmarkdown
.
Feel free to submit any issue or request.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we review your changes
Be sure to merge the latest from upstream
before making a pull request.