Local Development

This guide will help you set up GitHub Bubble Chart for local development.

Step 1: Fork and Clone the Repository

1. Fork the Repository – On GitHub, navigate to the GitHub Bubble Chart repository and click the "Fork" button in the top-right corner to create a copy in your account.

2. Clone Your Fork – Clone your forked repository to your local machine:

# Clone your forked repository (replace YOUR-USERNAME with your GitHub username)
git clone https://github.com/YOUR-USERNAME/github-bubble-chart.git

# Navigate into the project directory
cd github-bubble-chart

3. Add Upstream Remote (optional) – To keep your fork in sync with the original repository:

git remote add upstream https://github.com/teociaps/github-bubble-chart.git

Step 2: Install Dependencies

# Install all required packages
yarn install

Step 3: Set Up Environment Variables

The repository includes an .env.example file that lists all the required environment variables. Copy this to create your own .env file:

# Copy the example environment file
cp .env.example .env

# Edit the file with your preferred editor
nano .env  # or use any text editor

Make sure to add your GitHub token and adjust other variables as needed.

Important

Never commit your .env file to the repository. It contains sensitive information such as your GitHub token. The .env file is already in .gitignore to prevent accidental commits.

Step 4: Start the Development Server

You have two options to start the development server:

# Option 1: Standard development server on port 9000
yarn start

# Option 2: Run with Vercel dev environment on port 3000
yarn start:vercel

• Standard server will be available at: http://localhost:9000
• Vercel dev environment will be available at: http://localhost:3000

Note

Two different ports (9000 and 3000) are used to avoid "bad gateway" errors from port conflicts when running both servers.

Development Workflow

This project uses Husky for pre-commit hooks to automatically format and lint your code before commits. However, you can manually run these commands:

# Check for linting issues
yarn lint

# Fix linting issues automatically
yarn lint:fix

# Check for formatting issues with Prettier
yarn format

# Fix formatting issues automatically with Prettier
yarn format:fix

Additional Commands

GitHub Bubble Chart comes with several useful commands for development:

Command	Description
yarn build	Compiles TypeScript files
yarn test	Runs the test suite
yarn test:coverage	Runs tests with coverage report
yarn test:watch	Runs tests in watch mode
yarn clean	Removes the build directory

Warning

The yarn update-langs command is specifically used by an automatic GitHub workflow in the update-language-mappings branch. Do not run this command locally or manually push edits to the languageMappings.json file.

Troubleshooting

• Port Conflicts: If port 9000 or 3000 is already in use, you might need to modify the port in the environment variables
• GITHUB_TOKEN Issues: Ensure your token has appropriate permissions (repo scope for private repos)
• Build Errors: Try running yarn clean followed by yarn build to get a fresh build
• Husky Errors: If you encounter issues with Husky pre-commit hooks, run yarn lint:fix and yarn format:fix before committing again

---

🚀 For detailed information on how to contribute to the project and submit pull requests, please refer to the Contributing Guide.