BRUXX CLI 🔥

Overview

BRX TEMPLATE is a production-ready boilerplate for modern React projects. It eliminates the tedious setup process, letting you jump straight into coding with a preconfigured, optimized environment. Built with best practices, it’s designed for scalability, maintainability, and rapid deployment.

Why BRX TEMPLATE?

• Zero Setup Hassle: Preconfigured tools save hours of initial setup.
• Modern Stack: Leverages Vite, React, TypeScript, and more for a cutting-edge dev experience.
• Production-Ready: Includes Docker, CI/CD, linting, and testing out of the box.
• Focus on Code: Spend time building features, not configuring tools.

Prerequisites

Before you begin, ensure you have:

• Node.js: Version 18+ (check with node -v; .nvmrc specifies the exact version).
• npm: Version 8+ (comes with Node.js; verify with npm -v).
• Docker: Optional, for containerized deployment (install from docker.com).
• Git: For cloning and version control.

Installation

Step 1: Install the BRX CLI

The BRX CLI simplifies project creation. Install it globally:

npm install -g @bruxx/cli-tool

Step 2: Create Your Project

Run the CLI to scaffold your project:

npx create-brx-app

Follow the prompts to name your project (e.g., my-app).
The CLI sets up the directory, installs dependencies, and initializes Git.

Step 3: Navigate to Your Project

cd my-app

Step 4: Configure Environment

Copy .env.example to .env and adjust variables as needed:

cp .env.example .env

Example .env:

VITE_PORT=8080
VITE_BACKEND_API_BASE_URL=https://api.example.com

• VITE_BACKEND_API_BASE_URL: Set to your API’s base URL (e.g., https://jsonplaceholder.typicode.com for testing).
• No need to set NODE_ENV; it’s managed automatically ("test" for tests, "development"/"production" otherwise).

Project Structure

Here’s a quick overview of key directories and files:

my-app/
├── .github/              # GitHub Actions for CI/CD
├── .husky/               # Git hooks (e.g., linting on commit)
├── src/                  # Source code
│   ├── __tests__/        # Unit tests
│   ├── assets/           # Static assets (images, fonts)
│   ├── components/       # Reusable UI components
│   ├── lib/              # Utilities and API logic
│   │   ├── api/          # API controllers and services
│   ├── routes/           # TanStack Router routes
│   ├── store/            # Zustand state management
│   ├── types/            # TypeScript types
│   ├── app.tsx           # Root component
│   ├── env.ts            # Environment variable validation
│   ├── main.tsx          # Entry point
│   ├── router.tsx        # Router setup
├── .env                  # Environment variables
├── Dockerfile            # Docker configuration
├── package.json          # Scripts and dependencies
├── vite.config.ts        # Vite configuration

Running the Project

Development

Start the dev server:

npm run dev

• Opens at http://localhost:8080 (or your VITE_PORT).
• Hot Module Replacement (HMR) enabled via Vite.

Build

Compile for production:

npm run build

• Output goes to ./dist.

Preview

Test the production build locally:

npm run preview

Test

Run unit tests with Vitest:

npm run test

• Sets NODE_ENV="test" automatically, using an empty baseUrl for API mocks.

Core Features

API Integration

BRX TEMPLATE provides two API controllers for seamless HTTP requests:

• ControllerWithAuth: For authenticated endpoints (requires a token).
• ControllerWithoutAuth: For public endpoints (no token needed).

Example: Fetching Posts

Authenticated Request (e.g., user-specific posts):

// src/lib/api/controllers/post-controller.ts
import ControllerWithAuth from "@/lib/api/controllers/main/controller-with-auth";
import type { Post } from "@/types";

export default class PostController extends ControllerWithAuth {
  async getUserPosts(userId: number): Promise<Post[]> {
    return this.get(`/users/${userId}/posts`);
  }
}

export const { getUserPosts } = new PostController();

// Usage in a component
import { createQueryMethod } from "@/lib/api/query-methods";

const { data: posts } = createQueryMethod({
  key: ["user-posts", userId],
  fn: async () => {
    return await getUserPosts({ userId });
  },
}).useHook();

Unauthenticated Request (e.g., public posts):

import ControllerWithoutAuth from "@/lib/api/controllers/main/controller-without-auth";
import type { Posts } from "@/types";

export default class PostController extends ControllerWithoutAuth {
  constructor() {
    super();
  }

  async getAllPosts({ limit }: { limit?: number }) {
    try {
      const query = new URLSearchParams();

      if (limit) {
        query.append("_limit", String(limit));
      }

      return await this.apiService.get<Posts>(`/posts?${query}`);
    } catch (error) {
      this.handleError(error);
    }
  }
}

export const { getAllPosts } = new PostController();

// Usage in a component
const { data, isLoading, error } = createQueryMethod({
  key: ["posts", limit],
  fn: async () => {
    return await getAllPosts({ limit });
  },
}).useHook();

Deployment

Docker

Build and run with Docker:

docker build -t my-app .
docker run -p 8080:8080 my-app

CI/CD

GitHub Actions workflows in .github/workflows/ handle linting, testing, and deployment.
Configure secrets in your GitHub repo (e.g., DOCKERHUB_TOKEN).

Contributing

• Issues: Report bugs or suggest features on GitHub.
• Pull Requests: Fork, modify, and submit a PR with clear descriptions.

Next Steps

• Explore src/lib/api/ for API logic.
• Add routes in src/routes/.
• Customize src/store/ for state needs.
• Write tests in src/__tests__/.

Happy coding with BRX TEMPLATE! 🚀