Contributing

Thank you for your interest in Liam ERD! This document explains how you can engage with the project.

Please note we have a code of conduct, please follow it in all your interactions with the project.

Our contribution policy

Liam ERD is developed by the core team, and we do not accept unsolicited external Pull Requests. Pull requests opened without a prior invitation from the team will be closed without review.

This is not a judgment on the value of your work. Writing code has become inexpensive, but reviewing it carefully still depends on limited maintainer attention, and every external change widens the project's supply-chain surface. To keep Liam ERD secure and maintainable, code changes are merged by the core team.

This does not mean we don't want to hear from you — quite the opposite. There are many valuable ways to get involved, listed below.

How you can contribute

• Report a bug — open a bug report with clear steps to reproduce.
• Share an idea or ask a question — start a thread on GitHub Discussions.
• Report a security issue — please follow our Security Policy rather than opening a public issue.
• Spread the word — star the repo and tell others who might find Liam ERD useful.

Development environment setup

Before setting up the development environment, we recommend reviewing our Repository Architecture documentation to understand how our packages are organized.

To set up a development environment, please follow these steps:

1. Clone the repo

   git clone https://github.com/liam-hq/liam
   

2. Run the setup script

   ./scripts/setup-local-dev.sh
   

   This script will:

   • Install dependencies with pnpm
   • Create .env file from template
   • Start Supabase database
   • Configure Supabase authentication keys
   • Display next steps and test credentials

   Alternatively, you can run the setup steps manually:

   corepack enable
   corepack prepare
   pnpm install
   

3. Set up environment variables

   Copy the template environment file to create your local environment file:

   cp .env.template .env
   

   Required for basic local development:

   • Supabase keys will be automatically configured when you start the database (see step 4)

   For maintainers (Vercel team members only):

   Link your local project to the Vercel project and pull environment variables:

   pnpm vercel:link
   pnpm vercel:env-pull
   

   Next, create a .env.local file at the root directory and set values for the following keys:

   • OPENAI_API_KEY

4. Start the development server

   pnpm dev
   

5. Open apps

   package	url
   @liam-hq/app	http://localhost:3001
   @liam-hq/cli	http://localhost:5173
   @liam-hq/docs	http://localhost:3002
   @liam-hq/storybook	http://localhost:6006

   Test login credentials:

   • Login path: http://localhost:3001/app/login
   • Email: test@example.com
   • Password: liampassword1234

Issues and feature requests

You've found a bug in the source code, a mistake in the documentation or maybe you'd like a new feature? Take a look at GitHub Discussions to see if it's already being discussed. You can help us by submitting an issue on GitHub. Before you create an issue, make sure to search the issue archive -- your issue may have already been addressed!

Troubleshooting

Common Setup Issues

GitHub API Errors in Console If you see errors like [@octokit/auth-app] appId option is required, this is expected when GitHub environment variables are not configured. These errors don't affect core functionality - you can still use authentication, view projects, and access ER diagrams.

Login Page Redirects If /app/login redirects unexpectedly:

1. Ensure Supabase is running: pnpm --filter @liam-hq/db supabase:status
2. Check that Supabase keys are configured in .env
3. Restart the development server: pnpm dev

Database Connection Issues If you encounter database connection problems:

1. Stop Supabase: pnpm --filter @liam-hq/db supabase:stop
2. Start Supabase: pnpm --filter @liam-hq/db supabase:start
3. Re-run key extraction scripts:

   ./scripts/extract-supabase-anon-key.sh
   ./scripts/extract-supabase-service-key.sh
   

Missing Dependencies If you encounter missing dependency errors:

1. Ensure you have the correct Node.js version (check .nvmrc)
2. Clear node_modules and reinstall: rm -rf node_modules && pnpm install
3. Enable corepack: corepack enable && corepack prepare

Please try to create bug reports that are:

• Reproducible. Include steps to reproduce the problem.
• Specific. Include as much detail as possible: which version, what environment, etc.
• Unique. Do not duplicate existing opened issues.
• Scoped to a Single Bug. One bug per report.