Batch Craft Starter

An opinionated Craft CMS project starter that integrates VueJS and 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 CraftCMS starter package that allows us to get up and running and developing on projects quickly.

This starter comes set up, ready for for development with

• TailwindCSS
• VueJS
• craft-webpack - our Webpack build configuration
• Craft CMS with Twigpack
• Jest for Frontend testing
• Docksal configuration

Built With

• CraftCMS
• VueJS
• Tailwind CSS
• Webpack
• Jest
• Docksal

Getting Started

To create a new project using this starter, follow these steps

Prerequisites

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

Installation

1. Create a new project via composer, replacing 'myproject' with the desired project directory name

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

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.
2. Update the docksal configuration

Edit .docksal/docksal.env and set the Virtual Host domains to match the local host name you want to use eg. craftstarter.batch

VIRTUAL_HOST="craftstarter.batch"
VIRTUAL_HOST_CERT_NAME="craftstarter.batch"

Note: By default Docksal will only automatically resolve .docksal domains. More info here

3. Generate an SSL certificate. We recommend using the mkcert global addon which can be installed with

fin addon install --global mkcert

fin mkcert create

4. Reset vhost-proxy to pick-up the new certificate

fin system reset vhost-proxy

5. Start up the docksal containers

fin up

6. Install Craft via the command line installer

fin exec craft install

7. Install NPM dependencies

fin exec npm install

8. Build the asset files

fin exec npm run build

9. That's it!

Your new project should now be available at the configured domain and you should see a demo/Hello World 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

Josh Smith - @batchnz - josh@batch.nz

Jude Reid - @batchnz - jude@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.