How We Name Things

When building websites and applications it's crucial to establish and follow a consistent naming convention for your modules, data, and other development-related objects. At SanityPress, we have developed a set of guidelines that help streamline our development processes and ensure a more organized and maintainable codebase.

Why Naming Conventions Matter🔗

Naming conventions serve several important purposes:

1. Clarity: Well-chosen names make the purpose and content of each module or object immediately clear to developers, even if they are encountering the code for the first time.
2. Consistency: By following a standardized naming pattern, you ensure that all parts of your codebase use the same language and structure, making it easier for multiple developers to collaborate effectively.
3. Maintainability: Consistent naming helps you locate, understand, and modify specific modules or objects more easily as your project grows in size and complexity.

The SanityPress Naming Convention🔗

At SanityPress, we use a naming convention that consists of three main parts: the subject, the layout (optional), and a modifier (optional). The general pattern looks like this:

<subject>[-<layout>][.<modifier>]

You can see examples of how we apply this naming convention in our list of built-in modules.

Subject🔗

The subject represents the main content or purpose of the module. We typically use singular forms here, as the layout portion of the name can specify if it's a list or collection.

Examples: hero, testimonial, feature, accordion vs FAQ

Layout🔗

The layout part of the name describes the visual structure or arrangement of the module's content. Some common layout descriptors we use include:

• list — an array of items
  • stack — a vertical list; items "stacked" on top of each other
  • grid — a multi-column list
  • carousel — a swipe-able list
• tabbed — content hidden behind tabs

Examples: uvp-grid, testimonial-carousel, icon-text-stack

Modifier🔗

The modifier is an optional adjective appended to the end of the name to indicate any variations or special cases of an existing module.

Examples:

• hero vs hero.split
• hero.split vs hero.split.with-video
• testimonial vs testimonial.featured

Styling Options🔗

When it comes to styling options like background colors (light, dark, off-white, etc.) or list layouts (stack, grid, carousel, etc.), we recommend setting these within the module itself. This allows you to easily change the layout or appearance of the same content without creating a separate module. Just make sure to write the code for each condition in the frontend.

Putting It All Together🔗

By following this naming convention consistently across your Sanity.io projects, you'll create a more organized, maintainable, and scalable codebase. It's good to remember that Sanity is a headless CMS, so always assume content could reside in multiple locations and that the visuals could vary. Choosing clear, descriptive names for your modules and objects will make it easier for you and your team to work with your content effectively.

Can you picture the module's appearance simply by seeing its name?

By following SanityPress's thoughtful naming guidelines, you should be able to get a general sense of a module's content and layout without even seeing it. This intuitive naming system is a key part of our strategy for creating clear, consistent, and maintainable codebases.

At SanityPress, we've found that implementing this naming convention has greatly improved our development workflow and made our projects more maintainable in the long run. We encourage all Sanity.io developers to adopt a similar approach to naming their modules, data, and objects. By taking the time to establish clear guidelines and sticking to them consistently, you'll be well on your way to building better, more scalable applications with Sanity.

Tell us your suggestions!🔗

Let us know if you have any rules or naming conventions that you follow in your own projects! We'd love to hear about your development best practices and how they've helped streamline your workflow.