FAQ - Frequently Asked Questions
Quick answers to common questions about Constellation development.
General
Q: What is Constellation?
A: Constellation is a web-based collaborative workspace platform with rich text editing, graph visualization, and real-time collaboration features.
Q: What tech stack does it use?
A: Next.js 15, React 19, Tailwind CSS, TypeScript, Vitest, and Plate.js for the editor.
Q: Is this open source?
A: [Check repository for license and contribution guidelines]
Q: Can I contribute?
A: Yes! See CONTRIBUTING.md for guidelines.
Setup & Installation
Q: How do I get started?
A: Follow QUICK_START.md - takes 10 minutes!
Q: Do I need Docker?
A: No, but you need the backend services running. They can run locally or in Docker.
Q: What if I don't have Bun?
A: Install from bun.sh or use npm install -g bun
Q: Can I use npm or yarn instead of bun?
A: Not recommended. Bun is the official package manager for this project.
Q: Where do I set environment variables?
A: Create .env.local in the project root. See SETUP_GUIDE.md.
Q: Backend services won't start, what do I do?
A: Check TROUBLESHOOTING.md
Development
Q: Where do I add new components?
A: src/components/[feature]/ComponentName.tsx - See COMPONENTS.md
Q: How do I use existing components?
A: Import from @/src/components/ui/ComponentName - See COMPONENTS.md
Q: What's the file naming convention?
A: Components use PascalCase, files use kebab-case: MyComponent.tsx
Q: How do I create a custom hook?
A: Create src/hooks/use-my-hook.tsx following HOOKS.md patterns
Q: Where do I make API calls?
A: In services (src/services/) or custom hooks using apiClient - See SERVICES.md
Q: Should I use useState for global state?
A: No, use Context API or custom hooks. See ARCHITECTURE.md
Q: How do I add routes?
A: Create files in src/app/ using Next.js App Router. See ARCHITECTURE.md
Q: How do I protect admin routes?
A: Use useRequireAdmin hook or ProtectedRoute component
Styling
Q: How do I style components?
A: Use Tailwind CSS classes. See STYLING.md
Q: Where are custom styles?
A: Avoid custom CSS. Use Tailwind utilities or @apply in globals.css
Q: Can I use CSS modules?
A: Not recommended. Use Tailwind instead for consistency.
Q: How do I make responsive designs?
A: Use responsive prefixes: md:, lg:, etc. See STYLING.md
Q: Where's the color palette?
A: See tailwind.config.ts or STYLING.md
Q: How do I add dark mode?
A: Use dark: prefix: className="bg-white dark:bg-black"
Testing
Q: Do I need to write tests?
A: Yes, for all components and hooks. See TESTING.md
Q: How do I run tests?
A: bun test for watch mode or bun test:run once
Q: How do I test API calls?
A: Use MSW to mock APIs. See TESTING.md
Q: What's the coverage requirement?
A: > 80% for statements, branches, functions, and lines
Q: How do I test hooks?
A: Use renderHook from React Testing Library. See TESTING.md
Q: How do I debug tests?
A: Use screen.debug() or add console.logs. See TESTING.md
Code Quality
Q: Why are linting errors happening?
A: Run bun lint --fix to auto-fix most issues
Q: What TypeScript rules should I follow?
A: See CODE_STYLE_GUIDE.md
Q: Should I use any types?
A: Never! Always use proper types. It's part of code standards.
Q: How do I improve code quality?
A: Follow CODE_STYLE_GUIDE.md and use ESLint
Q: How do I find areas to refactor?
A: Look for components > 300 lines or repeated code patterns
Git & Contributing
Q: How do I create a pull request?
A: See CONTRIBUTING.md
Q: What's the commit message format?
A: <type>(<scope>): <subject> - See CONTRIBUTING.md
Q: Can I commit directly to main?
A: Never! Always create a feature branch and PR. See CONTRIBUTING.md
Q: How long should a PR be?
A: Keep it focused, ideally < 500 lines. Split large changes.
Q: What if my PR has merge conflicts?
A: Resolve them locally. See TROUBLESHOOTING.md
Q: How many reviewers do I need?
A: Typically 1-2 team members for approval
Performance
Q: How do I optimize a slow page?
A: See PERFORMANCE.md for strategies
Q: Should I use React.memo everywhere?
A: No, only on expensive components that re-render unnecessarily
Q: How do I know if my code is performant?
A: Use Chrome DevTools Performance tab. See PERFORMANCE.md
Q: What's a good bundle size?
A: < 200KB for main bundle (gzipped)
Internationalization
Q: How do I add translations?
A: Add keys to JSON files in public/locales/[lang]/
Q: Which languages are supported?
A: English (en) and French (fr)
Q: How do I use translations in components?
A: Use useTranslation() hook. See INTERNATIONALIZATION.md
Q: What if I forget a translation?
A: A placeholder will show. Add it to the JSON file.
Debugging
Q: My changes aren't showing up
A: Hard refresh (Ctrl+Shift+R) or check .next folder
Q: Console shows undefined errors
A: Check your imports and variable declarations
Q: API calls are failing
A: Check .env.local URLs and backend services
Q: Tests are failing randomly
A: Likely async issues. Use waitFor() or act() properly
Deployment
Q: How do I deploy?
A: See DEPLOYMENT.md
Q: Can I deploy to different platforms?
A: Yes, Vercel (recommended), AWS, GCP, Azure, etc.
Q: How do I set up environment variables in production?
A: Use platform-specific methods (env vars, secrets manager)
Q: How do I preview production build locally?
A: bun run build && bun start
Performance & Scaling
Q: How many users can it support?
A: Depends on backend infrastructure. Frontend scales well with code splitting.
Q: How do I handle large lists?
A: Use virtualization libraries or pagination. See PERFORMANCE.md
Q: Should I cache API responses?
A: Yes, for frequently accessed data. Use React Query or similar.
Security
Q: Is my data safe?
A: Data is encrypted in transit (HTTPS). See backend security docs.
Q: How do I handle sensitive data?
A: Never store in localStorage or client. Use secure HTTP-only cookies.
Q: Should I validate on frontend?
A: Yes, for UX. Always validate on backend too.
Miscellaneous
Q: Where are the docs?
A: You're reading them! Start at 00-OVERVIEW.md
Q: How often are docs updated?
A: With each significant change to the codebase
Q: Can I suggest doc improvements?
A: Yes! Create an issue or PR to improve docs
Q: How do I report a bug?
A: Create a GitHub issue with reproduction steps
Q: Who maintains this project?
A: [Check GitHub for maintainers]
Q: How do I get in touch?
A: [Slack, email, or GitHub discussions]
Quick Links
| Topic | Link |
|---|---|
| Setup | SETUP_GUIDE.md |
| Quick Start | QUICK_START.md |
| Architecture | ARCHITECTURE.md |
| Code Style | CODE_STYLE_GUIDE.md |
| Components | COMPONENTS.md |
| Hooks | HOOKS.md |
| Services | SERVICES.md |
| Testing | TESTING.md |
| Styling | STYLING.md |
| Contributing | CONTRIBUTING.md |
| Troubleshooting | TROUBLESHOOTING.md |
Still Have Questions?
- Search docs: Use Ctrl+F to search
- Check related docs: Follow the \"Related Documentation\" links
- Ask team: Create a discussion or ask in Slack
- Report issue: Create GitHub issue if it's a bug
Last Updated: January 2026
Got a question? Add it here! Create a PR with FAQ additions.