An opinionated Craft CMS project starter that integrates Vue.js, Tailwind CSS and Docksal configuration.
Explore the docs »
Report Bug ·
Request Feature
The idea behind this project was to create a Craft CMS starter that allows us to get up and running and developing on projects quickly.
This starter comes set up, ready for for development with:
- Tailwind CSS
- Vue.js
- craft-webpack - our Webpack build configuration
- Craft CMS with Twigpack
- Jest for frontend testing
- Docksal configuration
To create a new project using this starter, follow the below steps.
In order to use the this starter, you'll need to have Docksal up and running. You can find instructions at https://docksal.io/.
fin rc composer create-project batch/craft myproject --remove-vcsReplace 'myproject' with the desired project directory name.
Note: We recommend using Docksal's fin rc and fin exec commands, which will execute the commands on a standalone 'cli' container mapped to the current directory. This ensures the commands will run even if Composer or NPM are not installed locally.
The --remove-vcs flag will removes the batch/craft git metadata so this will be ready for use in a project repository.
We include an installer script that will finish setting up your project:
fin batch/install
After executing this and following the prompts your project should be available at the configured domain, and you should see a demo page to confirm.
This command sets up SSL certificates using mkcert, runs the Craft installer, installs the Twigpack plugin and npm dependencies and performs an initial build of the frontend assets. If you wish to do these steps manually, see the instructions below.
- Generate an SSL certificate. We recommend using the mkcert global addon which can be installed with:
fin addon install --global mkcert
fin mkcert create- Start up the Docksal container
fin up- Install Craft via the CLI
fin exec craft install- Install the Twigpack plugin
fin exec craft plugin/install twigpack- Install npm dependencies
fin exec npm install- Build the asset files
fin exec npm run buildThat's it! Your new project should now be available at the configured domain and you should see a demo page to confirm.
Install the depdendencies for the build tool
fin exec npm installProduction
fin exec npm run buildDevelopment
Run the development pipeline on the Docksal container. It will be available at webpack.{yourdomain}
fin exec npm run devUse the following commands to specifically generate a legacy or combined browser build during development
fin exec npm run dev-legacy
fin exec npm run dev-combinedSettings
The build settings in webpack.settings.js can be overridden at a project level by placing a webpack.settings.js file in the project root. This will be merged with the base webpack.settings.js file during build.
Example:
module.exports = {
paths: {
src: {
base: "./resources/",
css: "./resources/css/",
js: "./resources/js/"
}
}
};Webpack Config
Any custom Webpack config can be included by adding a webpack.config.js in the project root. This will be merged with the final Webpack config during build.
Example:
const path = require("path");
module.exports = {
resolve: {
alias: {
"#": path.resolve(__dirname, "src/vue/")
}
}
};We have provided a set of defaults to alias the src/ paths and additional entry points.
Use the fin exec craft plugin/install command to install any additional plugins.
Twigpack is required, and installed by default. We also include the following common plugins in the composer.json dependencies:
- Mailgun -
fin exec craft plugin/install mailgun - Redactor -
fin exec craft plugin/install redactor - SEOMatic -
fin exec craft plugin/install seomatic - Freeform -
fin exec craft plugin/install freeform - Navigation -
fin exec craft plugin/install navigation
On occasion we've found the need to run vanilla JS inline within a template (e.g. with Craft Commerce) and only run this code when our Vue app has mounted.
Our solution is to provide an event bus available at window.app that is instantiated within the head of the document via critical.js. To use the event bus, simply subscribe and publish to events like so:
Example: Subscribing to events
<script type="text/javascript">
window.app.on("vue-mounted", () => {
alert("vue has mounted!");
});
</script>Example: Publishing events
mounted() {
window.app.emit("vue-mounted");
}The vue-mounted event is provided out of the box to hook into from your twig templates.
Frontend
The starter comes with Jest installed and configured, plus the Vue testing framework helper library. To run the test suite, you can use the command
fin exec npm run test.
See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
- Jude Reid - @batchnz - [email protected]
- Alex Hatzipanis - @hatzipanis - [email protected]
Project Link: https://github.com/batchnz/craft
Thanks to all the hard work by the teams behind the tools used in this project.