README

Batch Craft Starter

An opinionated Craft CMS project starter that integrates Vue.js, Tailwind CSS and Docksal configuration.
Explore the docs »

Report Bug · Request Feature

Table of Contents

• About the Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Webpack Build Tool
  • Build Configuration
  • Craft Plugins
  • Mixing Inline Scripts with Vue
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

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

Built With

• Craft CMS
• Vue.js
• Tailwind CSS
• Webpack
• Jest
• Docksal

Getting Started

To create a new project using this starter, follow the below steps.

Prerequisites

In order to use the this starter, you'll need to have Docksal up and running. You can find instructions at https://docksal.io/.

Installation

Create a new project via composer

fin rc composer create-project batch/craft myproject --remove-vcs

Replace '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.

Run the installer

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.

Manual installation

1. Generate an SSL certificate. We recommend using the mkcert global addon which can be installed with: fin addon install --global mkcert

fin mkcert create

1. Start up the Docksal container

fin up

1. Install Craft via the CLI

fin exec craft install

1. Install the Twigpack plugin

fin exec craft plugin/install twigpack

1. Install npm dependencies

fin exec npm install

1. Build the asset files

fin exec npm run build

That's it! Your new project should now be available at the configured domain and you should see a demo page to confirm.

Usage

Webpack / Build Tool

Install the depdendencies for the build tool

fin exec npm install

Production

fin exec npm run build

Development

Run the development pipeline on the Docksal container. It will be available at webpack.{yourdomain}

fin exec npm run dev

Use 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-combined

Build Configuration

Settings

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.

Craft Plugins

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

Mixing Inline Scripts with Vue

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.

Testing

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.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

• Jude Reid - @batchnz - jude@batch.nz
• Alex Hatzipanis - @hatzipanis - alex@batch.nz

Project Link: https://github.com/batchnz/craft

Acknowledgements

Thanks to all the hard work by the teams behind the tools used in this project.