Use just for development instead on npm run

This behaves slightly more sensibly when calling it recursively.

.github/workflows/main.yaml

@@ -74,28 +74,28 @@ jobs:
             ${{ runner.os }}-composer-
 
       - name: Install dependencies
-        run: nix-shell --run 'npm run install-dependencies'
+        run: nix-shell --run 'just install-dependencies'
 
       - name: Check front-end code
         if: matrix.check_client
-        run: nix-shell --run 'npm run check:client'
+        run: nix-shell --run 'just check-client'
 
       - name: Check syntax of back-end code
-        run: nix-shell --run 'npm run lint:server'
+        run: nix-shell --run 'just lint-server'
 
       - name: Lint back-end code
         if: matrix.cs_fixer
-        run: nix-shell --run 'npm run cs:server'
+        run: nix-shell --run 'just cs-server'
 
       - name: Run unit tests
-        run: nix-shell --run 'npm run test:server'
+        run: nix-shell --run 'just test-server'
 
       - name: Analyse back-end code
         if: matrix.phpstan
-        run: nix-shell --run 'npm run analyse:server'
+        run: nix-shell --run 'just analyse-server'
 
       - name: Run integration tests
-        run: SELFOSS_TEST_STORAGE_BACKEND=${{ matrix.storage }} nix-shell --run 'npm run test:integration'
+        run: SELFOSS_TEST_STORAGE_BACKEND=${{ matrix.storage }} nix-shell --run 'just test-integration'
 
   deploy:
     name: 'Upload artefacts'
@@ -137,7 +137,7 @@ jobs:
       - name: Build a zipball
         id: zipball
         run: |
-          nix-shell --run 'npm run dist'
+          nix-shell --run 'just dist'
           echo "file_name=$(echo selfoss-*.zip)" >> "$GITHUB_OUTPUT"
           echo "version=$(echo selfoss-*.zip | sed -e 's/^selfoss-//' -e 's/\.zip$//')" >> "$GITHUB_OUTPUT"
 

CONTRIBUTING.md

@@ -9,7 +9,7 @@ If you discover a bug or wish to have a feature added, [report it to the issue t
 
 We accept [pull requests](https://github.com/fossar/selfoss/compare) with your changes.
 
-Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `npm run install-dependencies`, and then run the checks using `npm run check` before submitting a pull request. There is also `npm run fix`, that will attempt to fix the formatting.
+Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using <code><a href="https://github.com/casey/just">just</a> install-dependencies</code>, and then run the checks using `just check` before submitting a pull request. There is also `just fix`, that will attempt to fix the formatting.
 
 Please try to make commits small and self-contained. If you need to tweak something you previously committed, squash the new changes into the original commit before the PR is merged. `git commit --fixup` and `git rebase --autosquash` will help you, see https://dev.to/koffeinfrei/the-git-fixup-workflow-386d.
 

NEWS.md

@@ -41,6 +41,7 @@
 - Source filters are stricter, they need to start and end with a `/`. ([#1423](https://github.com/fossar/selfoss/pull/1423))
 - OPML importer has been merged into the React client. ([#1442](https://github.com/fossar/selfoss/pull/1442))
 - Web requests will send `Accept-Encoding` header. ([#1482](https://github.com/fossar/selfoss/pull/1482))
+- Developers, we replaced `npm` with [`just`](https://github.com/casey/just) for running build commands and other development tasks. Build the package using `just dist` and check the code using `just check`; see the `justfile` file in the root. ([#1492](https://github.com/fossar/selfoss/pull/1492))
 
 ## 2.19 – 2022-10-12
 **This version requires PHP ~~5.6~~ 7.2 (see known regressions section) or newer. It is also the last version to support PHP 7.**

README.md

@@ -67,15 +67,17 @@ We recommend [Reader For Selfoss](https://f-droid.org/packages/bou.amine.apps.re
 
 ## Development
 
-Selfoss uses [composer](https://getcomposer.org/) and [npm](https://www.npmjs.com/get-npm) for installing external libraries. When you clone the repository you have to issue `composer install` to retrieve the external sources.
+Selfoss uses [composer](https://getcomposer.org/) and [npm](https://www.npmjs.com/get-npm) for installing external libraries.
 
-For the client side, you will also need JavaScript dependencies installed by calling `npm install` in the `client/` directory. You can use `npm run install-dependencies` as a shortcut for installing both sets of dependencies.
+For convenience, we use [`just`](https://github.com/casey/just) command runner (like a modern `make`) to run common development tasks.
 
-We use [Parcel](https://parceljs.org/) (installed by the command above) to build the client side of selfoss. Every time anything in `client/` directory changes, you will need to run `npm run build` for the client to be built and installed into the `public` directory. When developing, you can also use `npm run dev`; it will watch for asset changes, rebuild the bundles as needed, and reload selfoss automatically. Upon switching between `npm run dev` and `npm run build`, you may need to delete `client/.cache`.
+When you clone the repository, you have to issue `composer install` to retrieve the external sources. For the client side, you will also need JavaScript dependencies installed by calling `npm install` in the `client/` directory. You can use `just install-dependencies` as a shortcut for installing both sets of dependencies.
 
-If you want to create a package with all the dependencies bundled, you can run `npm run dist` command to produce a zipball.
+We use [Parcel](https://parceljs.org/) (installed by the command above) to build the client side of selfoss. Every time anything in `client/` directory changes, you will need to run `just build` for the client to be built and installed into the `public` directory. When developing, you can also use `just dev`; it will watch for asset changes, rebuild the bundles as needed, and reload selfoss automatically. Upon switching between `just dev` and `just build`, you may need to delete `client/.cache`.
 
-Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `npm run install-dependencies`, and then run the checks using `npm run check` before submitting a pull request. There is also `npm run fix`, that will attempt to fix the formatting.
+If you want to create a package with all the dependencies bundled, you can run `just dist` command to produce a zipball.
+
+Every patch is expected to adhere to our coding style, which is checked automatically by CI. You can install the checkers locally using `just install-dependencies`, and then run the checks using `just check` before submitting a pull request. There is also `just fix`, that will attempt to fix the formatting.
 
 ## Credits
 

client/justfile

@@ -0,0 +1,31 @@
+fix: fix-js fix-styles
+
+fix-styles: fix-styles-lint fix-styles-prettify
+
+fix-styles-lint:
+	npm exec -- stylelint styles/*.scss --fix
+
+fix-styles-prettify:
+	npm exec -- prettier styles/*.scss --check --write
+
+fix-js:
+	npm exec -- eslint --ext .jsx,.js . --fix
+
+check: lint-js check-styles
+
+lint-js:
+	npm exec -- eslint --ext .jsx,.js .
+
+check-styles: check-styles-lint check-styles-prettify
+
+check-styles-lint:
+	npm exec -- stylelint styles/*.scss
+
+check-styles-prettify:
+	npm exec -- prettier styles/*.scss --check
+
+dev:
+	npm exec -- parcel watch index.html --dist-dir ../public/ --public-url ./
+
+build:
+	npm exec -- parcel build index.html --dist-dir ../public/ --public-url ./

client/package.json

@@ -44,19 +44,5 @@
     "process": "^0.11.10",
     "stylelint": "^16.0.0",
     "stylelint-config-standard-scss": "^13.0.0"
-  },
-  "scripts": {
-    "fix": "npm run fix:js && npm run fix:styles",
-    "fix:styles": "npm run fix:styles:lint && npm run fix:styles:prettify",
-    "fix:styles:lint": "npm run check:styles:lint -- --fix",
-    "fix:styles:prettify": "npm run check:styles:prettify -- --write",
-    "fix:js": "npm run lint:js -- --fix",
-    "check": "npm run lint:js && npm run check:styles",
-    "lint:js": "eslint --ext .jsx,.js .",
-    "check:styles": "npm run check:styles:lint && npm run check:styles:prettify",
-    "check:styles:lint": "stylelint styles/*.scss",
-    "check:styles:prettify": "prettier styles/*.scss --check",
-    "dev": "parcel watch index.html --dist-dir ../public/ --public-url ./",
-    "build": "parcel build index.html --dist-dir ../public/ --public-url ./"
   }
 }

composer.json

@@ -57,12 +57,5 @@
         },
         "allow-plugins": false,
         "sort-packages": true
-    },
-    "scripts": {
-        "cs": "php-cs-fixer fix --verbose --dry-run --diff",
-        "fix": "php-cs-fixer fix --verbose --diff",
-        "lint": "parallel-lint src tests",
-        "phpstan": "phpstan analyse --memory-limit 512M",
-        "test": "simple-phpunit --bootstrap tests/bootstrap.php tests"
     }
 }

docs/content/docs/development/setting-up.md

@@ -5,7 +5,7 @@ weight = 10
 
 selfoss makes use of many libraries to make our job as developers easier. To install them, you will need appropriate package managers. The server side uses [composer](https://getcomposer.org/) for PHP libraries and the client side uses [npm](https://www.npmjs.com/get-npm) for the JavaScript world.
 
-Then you will be able to run `npm run install-dependencies` to install the libraries, and `npm run dev` to start a program that will rebuild client-side assets when needed.
+Then you will be able to run <code><a href="https://github.com/casey/just">just</a> install-dependencies</code> to install the libraries, and `just dev` to start a program that will rebuild client-side assets when needed.
 
 To run the server side you will need at least [PHP](https://www.php.net/downloads) to be able to run the development server using `php -S 127.0.0.1:8000 run.php`. It would be also nice to have an array of database servers (MySQL and PostgreSQL) and web servers (Apache httpd and nginx) but the server built into PHP and SQLite will suffice for small changes.
 

docs/content/docs/project/release-checklist.md

@@ -4,9 +4,9 @@ weight = 40
 +++
 
 1. Update `NEWS.md` with highlights of changes that are not yet there. Set a release date.
-2. Update the version strings throughout the code base to the new release using `npm run bump-version 2.19` and commit the changes.
+2. Update the version strings throughout the code base to the new release using `just bump-version 2.19` and commit the changes.
 3. Commit the changes.
 4. Create a tag using `git tag 2.19`.
 5. Push the tag to GitHub `git push origin master --tags`, GitHub actions will automatically build the release tarball and publish the release on GitHub.
 6. Netlify will automatically build the website and deploy it.
-7. Change the versions to new snapshot `npm run bump-version 2.20-SNAPSHOT`, commit the changes, and push them to the repo to start a new cycle.
+7. Change the versions to new snapshot `just bump-version 2.20-SNAPSHOT`, commit the changes, and push them to the repo to start a new cycle.

flake.nix

@@ -63,6 +63,9 @@
               php
               php.packages.composer
 
+              # Command runner.
+              pkgs.just
+
               # Back-end code validation.
               php.packages.phpstan
 

justfile

@@ -0,0 +1,49 @@
+analyse-server:
+	composer exec -- phpstan analyse --memory-limit 512M
+
+bump-version version:
+	utils/bump-version.js {{version}}
+
+check: check-client check-server
+
+check-client:
+	just client/check
+
+check-server: lint-server cs-server test-server analyse-server
+
+cs-server:
+	composer exec -- php-cs-fixer fix --verbose --dry-run --diff
+
+dev:
+	just client/dev
+
+build:
+	just client/build
+
+dist:
+	python3 utils/create-zipball.py
+
+fix: fix-client fix-server
+
+fix-client:
+	just client/fix
+
+fix-server:
+	composer exec -- php-cs-fixer fix --verbose --diff
+
+install-dependencies: install-dependencies-client install-dependencies-server
+
+install-dependencies-client:
+	npm install --production=false --prefix client/
+
+install-dependencies-server:
+	composer install --dev
+
+lint-server:
+	composer exec -- parallel-lint src tests
+
+test-server:
+	composer exec -- simple-phpunit --bootstrap tests/bootstrap.php tests
+
+test-integration:
+	python3 tests/integration/run.py

package.json

@@ -11,25 +11,7 @@
     "npm": ">=7"
   },
   "scripts": {
-    "analyse:server": "composer run-script phpstan",
-    "bump-version": "$NODE utils/bump-version.js",
-    "check": "npm run check:client && npm run check:server",
-    "check:client": "npm run --prefix client/ check",
-    "check:server": "npm run lint:server && npm run cs:server && npm run test:server && npm run analyse:server",
-    "cs:server": "composer run-script cs",
-    "dev": "npm run --prefix client/ dev",
-    "build": "npm run --prefix client/ build",
-    "dist": "python3 utils/create-zipball.py",
-    "fix": "npm run fix:client && npm run fix:server",
-    "fix:client": "npm run --prefix client/ fix",
-    "fix:server": "composer run-script fix",
-    "install-dependencies": "npm run install-dependencies:client && npm run install-dependencies:server",
-    "install-dependencies:client": "npm install --production=false --prefix client/",
-    "install-dependencies:server": "composer install --dev",
-    "lint:server": "composer run-script lint",
-    "test:server": "composer run-script test",
-    "test:integration": "python3 tests/integration/run.py",
-    "postinstall": "npm run install-dependencies"
+    "postinstall": "just install-dependencies"
   },
   "cacheDirectories": [
     "client/node_modules"

src/controllers/Index.php

@@ -50,7 +50,7 @@ public function home(): void {
             $home = BASEDIR . '/public/index.html';
             if (!file_exists($home) || ($homeData = file_get_contents($home)) === false) { // For PHPStan: Error will be already handled by global error handler.
                 http_response_code(500);
-                echo 'Please build the client assets using `npm run build` or obtain a pre-built packages from https://selfoss.aditu.de.';
+                echo 'Please build the client assets using `just build` or obtain a pre-built packages from https://selfoss.aditu.de.';
                 exit;
             }