Best practices for Domino Apps

Follow these practices to help your apps stay clear, maintainable, and scalable as adoption grows across your organization.

Developer practices

These practices help you build Apps that are stable, reusable, and easy to maintain—especially as your team scales development across multiple environments and contributors.

Use clear titles and avoid hardcoded references

Give your App a clear, descriptive title that reflects its purpose, and avoid embedding fixed tokens or URLs that limit reusability.

  • Use names like "Churn Prediction Explorer" or "Marketing ROI Dashboard" rather than "test-app" or "new-dash-demo".

  • Explain the App’s purpose in the description field—include who it’s for, what data it uses, and any assumptions or limitations.

  • Avoid hardcoded tokens, URLs, usernames, or project paths in your App code. Use environment variables or configuration files instead.

  • This makes your App easier to share, maintain, and move between environments like dev, staging, and production.

Organize code cleanly

Structure your App’s code for clarity and maintainability by separating concerns and avoiding bloated single-file implementations.

  • Keep your main entry file (e.g., app.py) focused on layout, routing, or callbacks only.

  • Move business logic, data loading, and reusable functions into helper modules.

  • Use minimal shell scripts (app.sh) for launching the App and handling environment setup.

  • This approach simplifies debugging, encourages reuse, and makes collaboration easier.

Support multiple environments

Use branches and isolated environments to separate development, staging, and production workflows.

  • Create dedicated Git branches for each environment to test changes without affecting stable versions.

  • Pair each branch with a corresponding Domino compute environment, such as dev-env, prod-env.

  • Test new features side-by-side by publishing different App versions from separate branches.

  • This keeps experiments safe, reproducible, and easy to roll forward.

Version your environment

Avoid unexpected breakages by versioning your compute environments rather than editing them directly.

  • Clone your environment when making updates, instead of overwriting an existing one.

  • Use semantic versioning or meaningful tags (for example, v1.2-data-upgrade) to track changes.

  • Document the purpose of each version so you can match it to published Apps later.

  • This ensures App behavior stays consistent over time, even as your tooling evolves.

Review permissions intentionally

Control access to Apps thoughtfully to balance collaboration and security.

  • Set clear access levels: use Anyone can access for public tools, and restrict sensitive ones to specific users.

  • Review permissions before publishing or republishing—especially when cloning or renaming Apps.

  • Remember: App URLs can be shared externally. Use Domino’s access controls to enforce protection.

  • This helps prevent unintentional exposure and keeps your platform governance strong.

User experience and support

These tips ensure your Apps are approachable, well-documented, and easy for others to use, support, and extend—whether you’re sharing with a small team or a wider audience.

Link to supporting documentation

Help users understand how to use your App—and what it’s doing under the hood.

  • Add links to internal wikis, technical guides, or dashboards that explain data sources, outputs, and model behavior.

  • Mention key assumptions or limitations directly in the App description.

  • Consider adding an in-App link - something like a "Learn more" button - to surface docs during usage.

  • This reduces confusion and increases the App’s usefulness across teams.

Provide contact info for feedback

Make it easy for users to reach out when they have questions or run into issues.

  • Domino automatically includes an Email Owner option in the App toolbar—encourage users to use it.

  • Optionally, include a contact email or Slack handle in the App UI or footer.

  • For shared tools, consider a team alias or support channel instead of a personal address.

  • This keeps feedback flowing and helps you spot bugs or usability gaps early.

Next steps