Powerhouse Monorepo

This repository uses pnpm workspaces and Nx to manage a monorepo with multiple projects and packages.

How to Run this Repo
Linking Dependencies Between Projects and Packages
Adding a New Package or App
How to contribute to this project

How to Run this Repo

Clone the repo

git clone <repo-url>
cd <repo-directory>

Install the dependencies: pnpm install
Run a project or app: npx nx <run_command_for_the_package_or_app> <package_or_app_name>;

Linking Dependencies Between Projects and Packages

To link a dependency into a project, add it to your package.json and point the dependency version to workspace:*

package.json

{
  "name": "my-new-package",
  "version": "0.0.0",
  "scripts": {
    ...
  },
  "dependencies": {
    ...
    "@pgph/pkg-a": "workspace:*", // Link to a local dependency
    "@pgph/pkg-b": "workspace:*",
    "@pgph/pkg-c": "workspace:*"
  }
}

Adding a New Package or App

Pre-steps

Ensure that your package/app is properly configured to be built and published/released.
If deploying a package to npm, ensure that bundled files are included in the publish workflow and exclude unnecessary files (test files, config, etc.).

Steps

Add your package/app into the respective folder (packages/* or apps/*).
Install the dependencies: pnpm install
Ensure that your package.json points to version 0.0.0
Commit your changes: git commit -m "feat(<your_new_package_name>)!: initial package setup"
If pushing a new package to be deployed to npm, build the package first: npx nx <build_command> <your_new_package_name>
Perform an initial test release in your local environment: npx nx release --first-release --projects=<your_new_package_name> --dry-run
Perform the initial release in your local environment: (This step is required, otherwise releases from CI are not going to work): npx nx release --first-release --projects=<your_new_package_name>
- This process will create a new tag and release in GitHub, and push the new tag to GitHub.
- You'll be prompted if you want to create the release manually in your browser (this is going to prefill all the info for the release for you). Answer "yes" and verify in your browser that the release information is correct. Publish the release in github.
- Finally you'll be prompted if you want to publish the release to npm: answer "yes" if this is required for your package.

Add your package/app to the release GitHub Action workflow: If adding a new package to be released to npm, update the .github/worflows/release-package.yml:

---
name: Release Package

on:
workflow_dispatch:
    inputs:
    package:
        description: 'Choose a package'
        required: true
        default: 'packages/*'
        type: choice
        options:
            - '@pgph/pkg-a'
            - '@pgph/pkg-b'
            - '@pgph/pkg-c'
            - <add_your_new_package_name_here>
            - 'packages/*'

If adding a new app or a package requiring a special workflow, set up a new release configuration:


name: Your Custom Release

on:
workflow_dispatch:

jobs:
build:
    name: ...
    runs-on: ...
    permissions:
    contents: write
    id-token: write
    steps:
    ...
    - name: git config
        shell: bash
        run: |
        git config user.name "Github Actions Bot"
        git config user.email "-"

    - name: Update pkg version
        run: npx nx release --projects=<your_new_package/app_name> --skip-publish
        shell: bash
        env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    ...

Trigger future releases directly from GitHub Actions.

How to contribute to this project

Packages:

Currently, only the main branch is enabled in this project, which means all packages are deployed to NPM from the main branch. To contribute to a package, please follow these steps:

Create a feature branch from the main branch:

git pull origin main
git checkout main
git checkout -b feature/my-branch

Make your changes in the feature branch.
Once your changes are ready, commit them following the conventional commits standard:
- Try to keep your commits scoped (do not include files from multiple packages in a single commit).
- Include the package scope affected by your changes in the commit message, for example:
```
git commit -m "feat(document-model): my commit message"
```
Push your branch to GitHub and open a pull request (PR) against the main branch.
Once your PR is approved, merge it.
A GitHub Action will be triggered automatically after you merge your PR. This action will handle versioning and release the new version of the affected packages to NPM. Optionally, you can trigger the deployment of your package manually

powerhouse-inc / powerhouse

readme