Developer documentation for an app using District Core

Refer to Developers for Core related instructions such as commands, troubleshooting, info on specific services, etc...

Getting started

Creating a new project

cp .env.example .env
  • Replace all instances of district-app-boilerplate with the name of your app in .lando.yml, .lagoon.yml, cypress.config.js, docker-compose.yml and .env.* files.
  • Run lando start to build all app containers and start the app.
    You will most likely get URL resolve errors on first launch. Cancel resolution and run cmds below.
  • Run lando first-build to build remaining items and seed.
  • Create a new cypress project then update cypress.config.js with new projectId and .env.build with new CYPRESS_PROJECT_ID and CYPRESS_KEY

Setting up an existing project

  • Clone the repository
  • Copy env file
cp .env.example .env
  • Run lando start to build all app containers and start the app.
    You will most likely get URL resolve errors on first launch. Cancel resolution and run cmds below.
  • Run lando first-build to build remaining items and seed.

General dev principles

Where to put code?

Put all of your app business logic under new module(s) in the Modules folder.
This is where all of your overrides should live as you should stay away from app root files as much as possible.
Overriding core files creates additional maintenance and make upgrades more difficult.

Where does Core live?

The District core framework is a composer dependency so it lives in vendor/district/core-framework.
This app has been configured to run modules from both vendor/district/core-framework/Modules and Modules/ Most Laravel scaffolded files live in either:

  • vendor/district/core-framework such as app/Http/Kernel.php
  • Or in the Core module vendor/district/core-framework/Modules/Core

After composer install or composer upgrade, a number of files get copied from Core to this project. These are in .gitignore and not be overridden unless required.

What gets copied from Core and what can you override?

Core uses a composer plugin markocupic/composer-file-copier-plugin to copy and merge certain files/folders after a composer run.
This means that some changes may be lost after a composer update. Refer to the section "composer-file-copier-plugin" in the composer.json file of Core for the full list.
In a nutshell:

  • config/ is maintained by core. Any config override should be done in the app module. If really needed additional files can be added but exclusions will need to be added to .gitignore
  • resources/views and resources/lang provide basic core files and cannot be overridden.
  • General core files such as webpack.mix.js, artisan, server.php, ... are maintained by Core and cannot be overridden.
  • Any other folder in the app root will get merged with your changes.
  • The base theme is symlinked under themes/base for convenience

Theming

New theme

  • Add a new theme under themes/yourtheme and build with lando npm run --theme=yourtheme

District Core node modules

  • You can refer to the district-core-resources node module to access js and scss assets that live in the Core resources/common folder. -> e.g require district-core-resources/js/store.js
  • You can refer to the district-core-framework node module to access any other core asset such as district-core-framework/Modules/Timeline/Tests/Integration/helpers

Js aliases

  • Aliases to both core and app modules are created during webpack build using the value provided by the env var DISTRICT_MODULES_FOLDERS
  • Additional aliases to modules folders are setup in webpack.config.js, mainly to assist with inertia page asset resolution.

Upgrade Core

In composer.json, increment the version tag of the district/core-framework dependency and run lando composer update.

Dev changes on the District Core Framework / Local dev workflow.

You can setup a local version of core to make changes to the framework while working on your app:

  • Create a new folder at the root of your app like packages
  • Clone the latest version of core into it cd packages && git clone district/core-framework district-core
  • cd district-core and checkout a new dev branch, e.g git checkout feature/something
  • cd vendor/district
  • Move composer installed version mv district-core district-core-remote
  • Symlink package version in its place ln -s ../../packages/district-core core-framework
  • Develop
  • NOTE: you will have to repeat if you run composer install in project root

Option 2 - update composer.json

  • Change your composer.json config to use your local version of the framework:
{
    "require": {
        "district/core-framework": "dev-feature/something"
    },
    "repositories": [
        {
            "type": "path",
            "url": "packages/district-core",
            "options": {
                "symlink": true
            }
        }
    ],
    "minimum-stability": "dev",
    "prefer-stable": false
}
  • Run lando build to rebuild composer and frontend assets.
  • The core dependency is now symlinked in vendor. You can commit and push changes to core from packages/district-core.
  • **Do not forget to either not commit your composer.lock or update before a push as it is now running dev dependencies **

More info on particular composer workflows can be found in the following Confluence page