Best Practices

This guide offers recommendations and best practices for developing with Blocksweb to help you create more maintainable, efficient, and user-friendly applications.

Component Design

Keep Components Focused

Each Blocksweb component should have a single, well-defined responsibility:

// ✅ Good: A focused component with a clear purpose
const ProductCard: IBlockswebComponent = ({ title, price, image }) => {
  return (
    <div className="product-card">
      <img src={image} alt={title} />
      <h3>{title}</h3>
      <p className="price">${price}</p>
    </div>
  );
};

// ❌ Avoid: A component that does too many things
const ProductSection: IBlockswebComponent = ({ products, showFilters, categoryName }) => {
  // Handles filtering, product display, category header, etc.
  // This would be better split into multiple components
};

Make Components Reusable

Design components to be reusable across different contexts:

• Use props to make components configurable
• Avoid hardcoding values that might change
• Don't rely on external state unless necessary

Option Usage

Provide Meaningful Defaults

Always include sensible default values for your options:

// ✅ Good: Clear defaults that help users understand the component
SectionComponent.schema = {
  displayName: "Section Component",
  options: [
    {
      type: "text",
      name: "title",
      label: "Section Title",
      default: "Our Services",
    },
    {
      type: "number",
      name: "columns",
      label: "Number of Columns",
      default: 3,
    }
  ],
};

Use Descriptive Labels

Make your option labels clear and descriptive:

// ✅ Good: Descriptive labels
{
  type: "text",
  name: "buttonText",
  label: "Call to Action Button Text",
  default: "Learn More",
}

// ❌ Avoid: Vague labels
{
  type: "text",
  name: "btnTxt",
  label: "Button",
  default: "Click",
}

Content Management

Plan Your Data Structure

Before building your application:

1. Map out the entities and relationships in your data
2. Design database tables with scalability in mind
3. Consider how content editors will interact with the data

Create Meaningful Queries

When using the Query option type:

• Design queries that return exactly what components need
• Add clear labels and descriptions for content editors
• Consider caching for frequently accessed data

Performance Optimization

Minimize Component Re-renders

Optimize your components to prevent unnecessary re-renders:

• Use memoization techniques for expensive calculations
• Only update components when their props actually change
• Break large components into smaller, focused ones

Optimize Asset Loading

For better performance with images and other assets:

• Use appropriate image formats and sizes
• Implement lazy loading for images below the fold
• Consider using the <Image/> utility which handles optimization

Cross-Browser Testing

Always test your Blocksweb components across different browsers and devices to ensure consistent behavior and appearance.

SEO Considerations

When building pages with Blocksweb:

• Use proper heading hierarchy (h1, h2, h3, etc.)
• Include descriptive alt text for all images
• Ensure content is accessible to screen readers
• Structure your components to support semantic HTML

See Also

• Components - Learn about creating Blocksweb components
• Options - Explore available option types for your components
• Content Management - Understand how to manage content in Blocksweb