Extollo Development Tools

This is a wrapper package that provides scripts for setting up and working with the development environment for the Extollo framework.

The package.json contains scripts for cloning and setting up all of the first-party modules, and will install them so that they are dependencies of each-other on the filesystem. This way, a change in one module is reflected in the code of the other modules on development, without having to re-install them.

Installation

Simply clone this repo, then run the setup command. Requires Node 14+:

git clone https://code.garrettmills.dev/extollo/dev
cd dev
pnpm setup

Now, each of the sub-modules are available in the modules/ directory, and the main framework is setup in extollo/. If you view the package.json for any of the projects (the main framework, e.g.), you'll notice that the "version" of the packages has changed:

{
  "name": "@extollo/extollo",
  ...
  "dependencies": {
    "@extollo/cli": "link:../modules/cli",
    "@extollo/di": "link:../modules/di",
    "@extollo/i18n": "link:../modules/i18n",
    "@extollo/lib": "link:../modules/lib",
    "@extollo/orm": "link:../modules/orm",
    "@extollo/util": "link:../modules/util",
    "copyfiles": "^2.4.1",
    "typescript": "^4.1.3"
  },
  ...
}

This difference is because the packages are all installed from their locations on the filesystem, for ease of development.

Using forked repos

Extollo contributions should be done via pull-request on the Gitea server. To clone your user's copy of the Extollo repos instead of the official ones, use the --git argument:

npm run setup --git=git@code.garrettmills.dev:youruser/extollo-

For example, instead of using https://code.garrettmills.dev/extollo/lib for the modules/lib/ package, it will clone git@code.garrettmills.dev:youruser/extollo-lib.

Building Packages

To re-build all of the modules, you can run the pnpm build command. To rebuild a particular package, use pnpm build:<package name>.

Cleaning Up

To remove all of the cloned repositories, use pnpm clean. WARNING this WILL delete ALL files in the repositories, so be sure you don't have any work you want to save.

Common Processes

Adding a new first-party module

1. Create the repository in @extollo, based on the @extollo/_template repo.
2. Add a clone:module action to the scripts in package.json. Something like:

{
  "scripts": {
    // ...
    "clone:module_name": "git clone ${npm_config_git:-https://code.garrettmills.dev/extollo/}forms modules/forms"
  }
  // ...
}

3. Add the clone:module_name action to the clone:all action.
4. Add an install:module_name action to the scripts in package.json. Make sure it replaces any Extollo modules with symlink versions to the clones versions. For example:

{
  "scripts": {
    // ...
    "install:module_name": "cd modules/module_name && pnpm i --save @extollo/cli@file:../cli @extollo/di@file:../di @extollo/lib@file:../lib @extollo/util@file:../util && pnpm run build && cd ../.."
  }
  // ...
}

5. Add the install:module_name action to the install:all action.
6. Add a build:module_name action to the scripts ni package.json. For example,

{
  "scripts": {
    // ...
    "build:module_name": "cd modules/module_name && pnpm run build"
  }
  // ...
}

7. Add the build:module_name action to the build:all action.
8. Add the modules/module_name directory to the clean:modules action.
9. Install the repository you just added:

pnpm clone:module_name && pnpm install:module_name

10. Enable CI for the repo:
11. Sync the repositories, then activate the @extollo/module_name repository
12. Add the npm_password, drone_token, gitea_token, and notify_webhook_url secrets to the repo for extollo bot.
13. Edit .drone.yml to replace PACKAGE with the package name.