# Humand web

## Deployment

There are 2 deployment options:

- Testing (`develop`).
- Production (`master`).

To start the deployment actions on github we will need to push tags with the format
`<environment>-<version>`. Where `<environment>` can be `test` or `prod`, and `<version>` is an
integer, consecutive to the last used version on the selected environment.

**Important:**

If the `.env.<environment>` file changed since the last deployment, you will need to manually update
the secret of that file in github. To do this you first make a base64 version of the file, and then
go to the [secrets page of the repo](https://github.com/HumandDev/humand-web/settings/secrets/actions).
There you can update the `ENV_<environment>_FILE`: paste the base64 of your file, checking there is
no newlines, and save.
Always let the rest of the team know about these changes. :)

### Testing

- Get env base64:

```bash
$ base64 -i .env.development

// To directly copy the output to clipboard (on Linux):
$ base64 -i .env.development | xclip -sel clip
```

- Start deployment actions:

```bash
$ git tag test-<version>
$ git push
$ git push --tags
```

### Production

- Get env base64:

```bash
$ base64 -i .env.production

// To directly copy the output to clipboard (on Linux):
$ base64 -i .env.production | xclip -sel clip
```

- Start deployment actions:

```bash
$ git tag prod-<version>
$ git push
$ git push --tags
```

## Available Scripts

In the project directory, you can run:

### `bun start` or `bun run start`

Runs the app in development mode.<br>
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.

The page will automatically reload if you make changes to the code.<br>
You will see the build errors and lint warnings in the console.

### `bun run start:dev`

Runs the app with **material-hu & hu-translations plugins** enabled for real time development.<br>
See here [Development Mode - Vite plugins](https://github.com/HumandDev/material-hu/blob/main/vite/README.md)


### `bun test` or `bun run test`

Runs the test watcher in an interactive mode.<br>
By default, runs tests related to files changed since the last commit.

[Read more about testing.](https://facebook.github.io/create-react-app/docs/running-tests)

### `bun run build`

Builds the app for production to the `build` folder.<br>
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.<br>

Your app is ready to be deployed.

## Requirements

| Tool    | Version  | Enforced via                        |
| ------- | -------- | ----------------------------------- |
| Node.js | `24.11.1`| `engines` in `package.json` / `.nvmrc` |
| Bun     | `1.3.11` | `packageManager` in `package.json`  |

## Installation

### 1. Install NVM (if not installed)

Run the following command to confirm that `nvm` is installed:

```bash
nvm --version
```

If the command outputs the version of `nvm`, you're ready to proceed. Otherwise, follow the [installation guide](https://github.com/nvm-sh/nvm#installing-and-updating) to set up `nvm`.

### 2. Install Node.js v24.11.1

```bash
nvm install
```

The `nvm install` command reads the `.nvmrc` file and installs the correct version.

### 3. Use Node.js v24.11.1

```bash
nvm use
```

### 4. Install Bun

The project uses **Bun** as its package manager. The exact version is pinned in `package.json` via the `packageManager` field.

**Option A — via Homebrew:**

```bash
brew install bun
```

**Option B — specific version:**

```bash
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
```

### 5. Install dependencies

```bash
bun install
```


## Feature Flags Configuration
### Adding New Feature Flags

To add a new feature flag to the application, follow these steps:

1. Open `firebase.ts` in this directory
2. Add your new flag to the `FEATURE_FLAG_KEYS` object:

```typescript
export const FEATURE_FLAG_KEYS = {
  ENABLE_FAKE_FEATURE: 'ENABLE_FAKE_FEATURE',
  ENABLE_RATING: 'ENABLE_RATING',
  // Add your new flag here
  YOUR_NEW_FLAG: 'YOUR_NEW_FLAG',
} as const;
```

3. Add a default value in the `defaultConfig` object:

```typescript
export const defaultConfig: FeatureFlagDefaults = {
  [FEATURE_FLAG_KEYS.ENABLE_FAKE_FEATURE]: false,
  [FEATURE_FLAG_KEYS.ENABLE_RATING]: false,
  // Add your new flag's default value here
  [FEATURE_FLAG_KEYS.YOUR_NEW_FLAG]: false,
};
```

### Important Notes:

- All feature flags must be boolean values
- Default values should be `false` for new features
- After adding a new flag, you'll need to configure it in the Firebase Console

### Firebase Console Configuration

1. Go to the [Firebase Console](https://console.firebase.google.com/)
2. Select your project
   i. Development: Humand Test (humand-dev)
   ii. Staging: Humand QA (humand-qa)
   iii. Production: Humand (humand-f3269)
3. Navigate to **Run > Remote Config**
4. Add your new parameter with the exact same name as defined in `FEATURE_FLAG_KEYS`
5. Set the default value to match your `defaultConfig`
6. Publish the changes

## Feature Flags Hooks

### useFeatureFlag

A React hook for managing feature flags with Firebase Remote Config.

### Basic Usage

```typescript
import { useFeatureFlag } from 'src/hooks/useFeatureFlag';
import { FEATURE_FLAG_KEYS } from 'src/config/firebase';

function MyComponent() {
  const { value: isFeatureEnabled, isLoading } = useFeatureFlag(
    FEATURE_FLAG_KEYS.ENABLE_RATING
  );

  if (isLoading) {
    return <LoadingSpinner />;
  }

  return (
    <div>
      {isFeatureEnabled && <NewFeature />}
    </div>
  );
}
```

### useFeatureFlags (Multiple Flags)

```typescript
import { useFeatureFlags } from 'src/hooks/useFeatureFlag';
import { FEATURE_FLAG_KEYS } from 'src/config/firebase';

function MyComponent() {
  const { flags, isLoading } = useFeatureFlags([
    FEATURE_FLAG_KEYS.ENABLE_RATING,
    FEATURE_FLAG_KEYS.ENABLE_FAKE_FEATURE
  ]);

  if (isLoading) {
    return <LoadingSpinner />;
  }

  return (
    <div>
      {flags.ENABLE_RATING && <RatingFeature />}
      {flags.ENABLE_FAKE_FEATURE && <FakeFeature />}
    </div>
  );
}
```