Skip to main content

Best Practices

Automated Index Updates​

For optimal results, configure a CI/CD pipeline that automatically keeps your Constellation project index up-to-date. Set up your pipeline to trigger on commits or merges to your configured branch and run:

npm i -g @constellationdev/cli
constellation index

This ensures your codebase index remains synchronized with your latest changes, providing the most accurate and current results for your entire team when using Constellation.

CI/CD Best Practices:

  • Run indexing after successful builds and tests
  • Index only on the main/configured branch to maintain consistency
  • Use incremental indexing by default (it's automatic)
  • Consider running on a schedule (e.g., nightly) as a backup
  • Monitor indexing job success and alert on failures

Version Control The Configuration File​

Be sure to commit your constellation.json file to share team settings and ensure consistent functionality across your development team.

Indexing Strategy​

When to Use Full vs Incremental Indexing​

Constellation defaults to incremental indexing, which only processes changed files. This is the recommended approach for most situations:

Use Incremental Indexing (Default):

  • Regular development workflow
  • CI/CD pipeline runs
  • Minor code changes and updates
  • Daily development activities

Use Full Indexing (--full flag):

  • Initial project setup
  • After major refactoring that affects many files
  • When switching to a different primary branch/trunk permanently
  • After changing language configurations in constellation.json
  • If you suspect the index is out of sync

Example:

# Regular updates (incremental, default)
constellation index

# Major refactor or initial setup
constellation index --full

Git Branch Management​

Always index on your configured branch to maintain index consistency:

  • Verify you're on the correct branch before indexing
  • Don't mix commits from different branches in the same index
  • Use separate project configurations for long-lived feature branches if needed
  • Let git validation checks run (don't use --dirty in production)

Configuration Optimization​

note

Files ignored by .gitignore are automatically excluded from Constellation indexing. The exclude configuration is for additional patterns beyond your .gitignore.

Exclude Patterns​

Optimize indexing performance by carefully configuring exclude patterns in constellation.json. The exclude field accepts glob pattern strings:

{
  "exclude": ["**/dist/**", "**/build/**", "**/.next/**", "**/node_modules/**"]
}

Recommended Exclusions:

  • Build output directories (dist, build, out, .next)
  • Dependency directories (node_modules, vendor)
  • Generated code directories
  • Test coverage reports
  • Temporary files