Skip to content

Latest commit

 

History

History
177 lines (118 loc) · 5.39 KB

DEVELOPERS.md

File metadata and controls

177 lines (118 loc) · 5.39 KB

Developer Guide

Requirements

Node.js v24

bun package manager

brew tap oven-sh/bun # for macOS and Linux
brew install bun
# Upgrading bun itself
bun upgrade

# other global packages you will need
bun add -g turbo

Nhost CLI

  • The CLI is primarily used for running local E2E tests and development
  • Please refer to the installation guide if you have not installed it yet

File Structure

The repository is organized as a monorepo, with the following structure (only relevant folders are shown):

assets/            # Assets used in the README
docs/              # Developer Documentation
apps/
 web/              # Dashboard WebApp
 docs/             # Documentation website
 smart/            # AI experemental features
 offline/           # local-first/offline-first demo app
patches/           # bun patched dependencies
packages/          # Core packages
integrations/      # These are packages that rely on the core packages

Get started

Installation

First, clone this repository:

git clone https://github.com/xmlking/spectacular.git

Then, install the dependencies with bun:

cd spectacular
bun install

Development

Although package references are correctly updated on the fly for TypeScript, example projects and the dashboard won't see the changes because they are depending on the build output. To fix this, you can run packages in development mode.

Running packages in development mode from the root folder is as simple as:

turbo run web#dev -- --open

Our packages are linked together using BUN's workspace feature. Next.js and Vite automatically detect changes in the dependencies and rebuild everything, so the changes will be reflected in the examples and the dashboard.

Edit Documentation

The easier way to contribute to our documentation is to go to the apps/docs folder and follow the instructions to start local development:

# not necessary if you've already done this step somewhere in the repository
turbo run docs#dev

Run Test Suites

Unit Tests

You can run the unit tests with the following command from the repository root:

turbo run console#test:unit

E2E Tests

Each package that defines end-to-end tests embeds their own Spectacular configuration, that will be automatically when running the tests. As a result, you must make sure you are not running the Nhost CLI before running the tests.

You can run the e2e tests with the following command from the repository root:

turbo run console#test:integration

Linting and Formatting

We uses biome as a linter and formatter. To just check for errors, run

turbo run biome:check

To fix them, run

turbo run format
turbo run lint

both at the root of the monorepo. Not all errors can be fixed automatically.

There are a good number of errors in much of the older code, but please try not to introduce new ones.

Changesets

If you've made changes to the packages, you must describe those changes so that they can be reflected in the next release. We use changesets to support our versioning and release workflows. When you submit a pull request, a bot checks if changesets are present, and if not, it asks you to add them.

To create a changeset, run the following command from the repository root:

bun changeset

This command will guide you through the process of creating a changeset. It will create a file in the .changeset directory.

You can take a look at the changeset documentation: How to add a changeset.

Selecting the Version

When you create a changeset, you will be asked to select the version of the package that you are bumping. The versioning scheme is as follows:

  • major
    • For breaking changes (e.g: changing the function signature, etc.)
    • Should be avoided as much as possible as it will require users to update their code. Instead, consider supporting both the old and the new API simultaneously for a while.
    • For example: v1.5.8 -> v2.0.0
  • minor
    • For new features (e.g: adding a new page to the dashboard, etc.)
    • For example: v1.5.8 -> v1.6.0
  • patch
    • For bug fixes (e.g: fixing a typo, etc.)
    • For example: v1.5.8 -> v1.5.9

Writing Good Changesets

A concise summary that describes the changes should be added to each PR. This summary will be used as the changeset description.

The following structure is used for describing changes:

  • The type of the change:

    • fix
    • feat
    • chore
    • docs

  • The scope of the change (broader scopes (e.g: dashboard, hasura-storage-js, etc.) are not recommended as GitHub Releases already contain which project is being bumped):

    • projects
    • deployments
    • deps
    • etc.

  • A short summary of the changes that were made

Examples:

  • fix(deployments): use correct timestamp for deployment details
  • chore(deps): bump @types/react to v18.2.8
  • feat(secrets): enable secrets
  • etc.

You can always take a look at examples of changesets in the GitHub Releases section.