BigCommerce Stencil: Mastering Custom Themes and Blueprint Migrations

---

Outgrowing your current BigCommerce theme means you need more control, faster performance, and design flexibility that older frameworks can’t deliver. Whether you’re building custom storefronts or migrating from Blueprint, understanding BigCommerce Stencil is essential for creating high-performing e-commerce experiences that scale with your business.

This guide covers everything from Stencil framework fundamentals to advanced customization techniques, Blueprint migration strategies, and when to bring in a BigCommerce Stencil developer. You’ll learn practical steps to leverage Stencil’s capabilities while avoiding common pitfalls that slow down development and impact site performance.

Summary

• Stencil Framework Architecture: Learn how Handlebars templating, modular components, and theme configuration work together for flexible customization
• Custom Theme Development: Understand local setup, CLI tools, and best practices for building scalable Stencil themes from scratch
• Blueprint to Stencil Migration: Follow a proven process for transitioning legacy Blueprint stores to modern Stencil architecture
• Advanced Customization: Explore custom widgets, API integration, and performance optimization techniques used by experts
• Developer Resources: Access essential tools, documentation, and when to hire specialized talent for complex projects

What Is BigCommerce Stencil?

BigCommerce Stencil represents the platform’s modern theme engine, replacing the legacy Blueprint framework in 2016. This architecture gives developers and merchants greater control over storefront customization while maintaining mobile responsiveness and performance standards.

Core Framework Components

Stencil BigCommerce operates through three primary layers. The templating layer uses Handlebars.js for dynamic content rendering, allowing developers to separate logic from presentation. The configuration layer manages theme settings through JSON files, making it easier to create merchant-friendly customization options without touching code. The asset compilation layer handles CSS, JavaScript, and image optimization through Webpack bundling.

Unlike Blueprint’s rigid structure, Stencil themes support real-time preview, local development environments, and modular component architecture. This flexibility enables faster iteration cycles and cleaner code organization.

Why Stencil Replaced Blueprint

Blueprint’s limitations became apparent as mobile commerce grew and merchant customization needs evolved. The older framework lacked responsive design tools, required server-side changes for preview testing, and made simple design updates unnecessarily complex.

Stencil addressed these gaps with mobile-first architecture, theme editor capabilities for non-technical users, and improved page load speeds through optimized asset delivery. The shift also aligned BigCommerce with modern JavaScript frameworks and development workflows that attract experienced developers.

Feature	Stencil	Blueprint
Responsive Design	Built-in mobile optimization	Manual responsive coding
Local Development	Full CLI support	Limited local testing
Customization UI	Theme Editor for merchants	Code-only changes
Performance	Optimized asset bundling	Slower load times

Setting Up Your BigCommerce Stencil Development Environment

Building BigCommerce Stencil themes requires specific tools and environment configuration. This section walks through the complete setup process for local development.

Required Tools and System Prerequisites

Start with Node.js version 14.x or higher installed on your system. The Stencil CLI requires npm (Node Package Manager) for dependency management and theme operations. You’ll also need a code editor like Visual Studio Code with Handlebars syntax support.

Create a BigCommerce store account with API credentials. Navigate to Advanced Settings > API Accounts in your store control panel, then generate store-level API credentials with OAuth scope for Themes (modify) and Content (modify). Store these credentials securely as you’ll need them for CLI authentication.

Installing Stencil CLI

Open your terminal and run the installation command:

npm install -g @bigcommerce/stencil-cli

Verify installation with stencil –version to confirm the CLI installed correctly. If you encounter permission errors on Mac or Linux, use sudo npm install -g @bigcommerce/stencil-cli instead.

Downloading and Configuring a Base Theme

Choose a starter theme from BigCommerce’s repository. The Cornerstone theme serves as the most common starting point, offering a complete e-commerce template with all standard features implemented.

Clone your chosen theme using Git:

git clone https://github.com/bigcommerce/cornerstone.git

cd cornerstone

npm install

Initialize your local environment by running stencil init. The CLI will prompt for your API credentials, store URL, and port preferences. This creates a .stencil configuration file that connects your local environment to your BigCommerce store.

Testing Your Local Environment

Launch the local development server with stencil start. The CLI bundles theme assets and starts a local preview at http://localhost:3000 by default. Any changes you make to templates, styles, or scripts trigger automatic browser refresh.

Test basic functionality by modifying a template file and confirming changes appear in your browser. Check the console for JavaScript errors and verify that all theme features work as expected before proceeding to customization.

For developers working on Shopify to BigCommerce migration projects, understanding both platforms’ development environments helps ensure smoother transitions and better planning for theme recreation work.

Understanding Stencil Theme Architecture

Stencil BigCommerce architecture follows a modular pattern that separates concerns and enables scalable development. Knowing how these pieces fit together helps you build maintainable custom themes.

Template Structure and File Organization

Stencil themes organize files into logical directories. The templates/ folder contains page-level Handlebars files (home.html, category.html, product.html), while templates/components/ holds reusable partial templates. The assets/ directory manages all static resources including SCSS, JavaScript modules, and images.

Configuration files live in the theme root. The config.json file defines theme settings that appear in the merchant’s theme editor. The schema.json validates these settings and their acceptable values. The .stencil file stores API credentials and shouldn’t be committed to version control.

Handlebars Templating System

Handlebars provides the templating logic for Stencil themes. Basic syntax uses double curly braces for variable output: {{product.title}} renders the product name. Block helpers like {{#if}} and {{#each}} enable conditional logic and loops without complex JavaScript.

Custom helpers extend templating functionality. BigCommerce includes dozens of built-in helpers for common operations like {{lang}} for translations, {{cdn}} for asset URLs, and {{region}} for content zones. You can also register custom helpers in assets/js/theme/global.js for specialized logic.

Partial templates promote code reuse. The {{> components/products/card}} syntax includes a product card component, passing context data as needed. This approach keeps templates clean and makes updates easier when design changes affect multiple pages.

Front Matter and Page Context

Each template file starts with front matter enclosed in triple dashes. This YAML section defines page-specific settings like page type, resource hints, and custom data queries.

---

product:

    videos:

        limit: {{theme_settings.productpage_videos_count}}

    reviews:

        limit: {{theme_settings.productpage_reviews_count}}

---

The front matter controls what data loads on each page, reducing unnecessary API calls and improving performance. Strategic use of data queries ensures templates have exactly the information they need without over-fetching.

CSS and JavaScript Asset Management

Stencil compiles SCSS files through a Webpack pipeline. The main stylesheet at assets/scss/theme.scss imports modular partials organized by function (layout, components, utilities). Variables in assets/scss/settings/ control colors, typography, and spacing across the entire theme.

JavaScript follows a similar modular pattern. The assets/js/theme/ directory contains feature-specific modules that initialize on relevant pages. The bundle process tree-shakes unused code and minifies output for production, though developers must structure modules properly to enable effective optimization.

Directory	Purpose	Key Files
templates/pages/	Page-level templates	home.html, product.html, category.html
templates/components/	Reusable partials	product-card.html, header.html
assets/scss/	Stylesheets	theme.scss, settings/
assets/js/	JavaScript modules	global.js, page-specific modules

Building Custom BigCommerce Stencil Themes

Creating a custom BigCommerce Stencil theme from scratch gives you complete control over storefront design and functionality. This section covers the development process from planning to deployment.

Planning Your Custom Theme

Define requirements before writing code. Document must-have features, custom page layouts, and unique functionality needs. Sketch wireframes for key pages (homepage, product detail, category, cart, checkout) to visualize information hierarchy and user flows.

Consider performance budgets upfront. Set targets for Time to Interactive (TTI), Largest Contentful Paint (LCP), and total page weight. These constraints guide architectural decisions and prevent performance issues that are harder to fix later.

Audit existing theme features you’ll need to replicate or improve. Review product filtering, search functionality, customer account pages, and checkout integration points. Understanding these dependencies prevents missing critical e-commerce capabilities.

Creating Base Templates

Start with the homepage template as your foundation. Build the header and footer as separate components since they appear across all pages. Implement responsive navigation that works on mobile devices and desktop screens.

Move to product and category templates next, as these drive most traffic and conversions. Focus on clear product information hierarchy, high-quality image displays, and intuitive add-to-cart functionality. Category pages need effective filtering and sorting that performs well with large catalogs.

Cart and checkout templates require careful handling of form validation, shipping calculation, and payment integration. While BigCommerce manages checkout logic, your theme controls presentation and must align with backend functionality.

Implementing Custom Functionality

Custom features often require extending Stencil’s capabilities through API integration. The Storefront API enables dynamic cart updates, wishlist functionality, and customer data access without page refreshes.

Custom product options might need specialized rendering logic. Create custom Handlebars helpers or JavaScript modules that handle complex option dependencies, conditional pricing, or unique configurators beyond standard option sets.

Third-party integrations (reviews, loyalty programs, marketing tools) typically provide embed codes or API documentation. Plan integration points in your templates and ensure styling matches your design system rather than looking like tacked-on widgets.

For stores combining multiple platforms, understanding BigCommerce integration patterns helps you build more flexible, maintainable custom functionality that works with other systems.

Testing and Quality Assurance

Test across devices and browsers before deployment. Use actual mobile devices for touch interaction testing, not just desktop browser emulation. Common issues include hover states that don’t work on touch screens and tap targets that are too small.

Validate against BigCommerce theme requirements. Run the theme checker utility provided in Stencil CLI to catch common errors. Verify all required templates exist and implement necessary functionality.

Performance testing should include:

• Lighthouse audits for Core Web Vitals
• Full page load testing on 3G connections
• Asset size verification
• JavaScript execution profiling

Load test forms with various valid and invalid inputs. Verify error messages display clearly and form recovery works as expected.

Migrating from BigCommerce Blueprint to Stencil

The BigCommerce Blueprint to Stencil migration process requires methodical planning and execution. Legacy Blueprint stores need careful transition strategies to minimize downtime and preserve functionality.

Assessing Your Blueprint Store

Start with a comprehensive inventory of customizations. Document all custom template modifications, third-party app integrations, and unique functionality not available in standard Blueprint. Screenshot key pages and functionality to reference during rebuild.

Review your current code quality and technical debt. Migration presents an opportunity to eliminate workarounds and deprecated code patterns that accumulated over time. Identify which customizations still serve business needs versus which can be improved or eliminated.

Extract custom CSS and JavaScript that isn’t template-dependent. Well-written styles and scripts may port to Stencil with minimal changes, saving development time compared to starting from scratch.

Planning Your Migration Approach

Choose between parallel development and staged migration. Parallel development builds the complete Stencil theme before switching, minimizing risk but requiring more upfront investment. Staged migration moves sections gradually, reducing initial costs but increasing complexity during transition.

Create a detailed migration checklist organized by page type. List all templates, components, and features that need recreation in Stencil. Assign priority levels based on business impact and traffic patterns.

Schedule migration during low-traffic periods when possible. Plan for extended testing windows and have rollback procedures ready. Communicate timeline and potential issues to stakeholders before starting.

Template Conversion Process

Blueprint and Stencil use different templating languages. Blueprint’s PHP-based WebDAV system doesn’t directly translate to Stencil’s Handlebars templates. Manual conversion requires understanding how each system accesses product data and renders content.

Start with simpler templates (contact, about pages) to build conversion expertise before tackling complex product and category templates. For each Blueprint template:

1. Identify data variables and their Stencil equivalents
2. Convert conditional logic to Handlebars helpers
3. Rebuild loops using {{#each}} syntax
4. Test data output matches Blueprint functionality

Custom HTML widgets and content blocks need recreation in Stencil’s widget system. Export content from Blueprint, then reimport through Stencil’s Page Builder or widget framework.

Preserving SEO and URL Structure

Maintain existing URL patterns to preserve search rankings and external links. Configure redirects for any URL changes using BigCommerce’s redirect management or external solutions if patterns changed significantly.

Verify meta titles, descriptions, and structured data carry over correctly. Stencil handles these differently than Blueprint, requiring template updates to ensure proper output.

Test canonical URLs, pagination, and alternate language tags if running multilingual stores. These technical SEO elements often break during migrations and require specific attention.

Post-Migration Testing and Optimization

Conduct thorough testing across all page types and user flows. Key areas include:

• Product browsing and filtering
• Cart and checkout processes
• Customer account functionality
• Form submissions and data capture
• Third-party integration functionality

Compare Stencil performance against Blueprint baseline. Stencil should improve load times, but poorly optimized custom code can negate these gains. Profile JavaScript execution and optimize bottlenecks.

Monitor error logs and customer support tickets closely for the first few weeks post-migration. Users may report edge cases or functionality gaps not caught during testing.

For stores also considering other platforms, reviewing BigCommerce alternatives helps determine if migration to Stencil or moving to a different platform better serves long-term goals.

Migration Phase	Duration	Key Activities
Assessment	1-2 weeks	Inventory, documentation, planning
Development	4-8 weeks	Template conversion, feature rebuild
Testing	2-3 weeks	QA, performance, cross-browser testing
Launch & Monitor	2-4 weeks	Deployment, issue resolution, optimization

Advanced Stencil Customization Techniques

BigCommerce Stencil expert developers leverage advanced techniques to build sophisticated storefronts that go beyond basic theme customization.

Custom Widgets and Page Builder Integration

Stencil’s widget framework allows you to create custom Page Builder components merchants can drag and drop. Build widgets by defining a schema that specifies configuration options, then create the template that renders the widget.

Register custom widgets in your theme’s schema.json file with widget type, label, template path, and configuration schema. Merchants then access these through the Page Builder interface alongside default widgets.

Well-designed custom widgets balance flexibility with simplicity. Provide essential customization options without overwhelming users with unnecessary controls. Include preview functionality so merchants see changes before saving.

Storefront API Integration

The Storefront API enables dynamic functionality without page reloads. Common use cases include updating cart contents, managing wishlists, and loading product data asynchronously. API calls use GraphQL syntax for precise data queries that minimize payload size.

Implement API calls through JavaScript fetch requests with proper authentication. Structure your code to handle loading states, errors, and success responses gracefully. Cache responses when appropriate to reduce server load and improve perceived performance.

Rate limiting applies to Storefront API requests. Design your implementation to batch requests where possible and implement exponential backoff for retries on failed requests.

Performance Optimization Strategies

Lazy load images below the fold using native browser loading attributes or intersection observers. This technique dramatically improves initial page load by deferring off-screen content.

Code split JavaScript bundles to load only necessary code per page. Stencil’s Webpack configuration supports dynamic imports that create separate bundles for feature-specific modules.

Optimize custom fonts by subsetting character ranges, using font-display strategies, and preloading critical font files. Typography significantly impacts visual stability and page performance metrics.

Implement resource hints (preconnect, dns-prefetch, prefetch) for third-party domains and predictable user navigation. These browser hints reduce latency for subsequent requests.

Custom Checkout Solutions

While BigCommerce controls the checkout flow, you can customize presentation through their Checkout SDK. This JavaScript library provides access to checkout state and enables UI customization without rebuilding core functionality.

Build custom checkout experiences by creating a single-page application that uses the Checkout SDK for backend communication. This approach offers maximum flexibility but requires substantial development investment.

Simpler customization uses the Checkout SDK to modify default checkout appearance through custom CSS and limited script injection. This balances customization needs with development effort for most use cases.

Working with BigCommerce Stencil Developers

Hiring a BigCommerce Stencil developer makes sense for complex projects that exceed internal capabilities. Understanding when and how to engage external expertise ensures better outcomes.

When to Hire Specialized Talent

Complex custom features requiring deep Stencil knowledge justify hiring specialists. Examples include custom configurators, advanced filtering systems, or sophisticated API integrations that go beyond standard e-commerce functionality.

Blueprint to Stencil migrations often benefit from experienced developers who understand both frameworks and can execute transitions efficiently. Migration specialists reduce risks and timeline compared to learning through trial and error.

Performance optimization for high-traffic stores may require expertise in Stencil’s compilation pipeline, caching strategies, and BigCommerce-specific optimization techniques that general developers might miss.

Evaluating Developer Expertise

Look for developers with Stencil-specific portfolios demonstrating relevant project experience. Review their GitHub contributions, particularly around BigCommerce repositories or Stencil-related open source projects.

Technical assessment should cover Handlebars templating, JavaScript module patterns, SCSS architecture, and familiarity with BigCommerce APIs. Ask candidates to explain how they’ve solved specific challenges in past Stencil projects.

Communication skills matter as much as technical ability. Developers need to explain technical decisions to non-technical stakeholders and work collaboratively with designers, marketers, and business owners.

Managing Stencil Development Projects

Clear requirements prevent scope creep and misaligned expectations. Document functionality specifications, design deliverables, and performance targets before development starts. Include acceptance criteria for each feature.

Establish development workflows that include version control, code review, and testing protocols. Require developers to work in feature branches and submit pull requests for review before merging changes.

Schedule regular progress reviews to catch issues early. Weekly demos with working functionality help ensure development stays aligned with business needs and allows course correction if needed.

For comprehensive BigCommerce development services, partnering with agencies that specialize in the platform provides access to diverse expertise and established processes that accelerate project delivery.

Essential Tools and Resources for Stencil Development

Success with BigCommerce Stencil themes depends on leveraging the right tools and staying current with framework updates.

Official Documentation and Learning Resources

BigCommerce Developer Documentation serves as the primary reference for all Stencil capabilities. The documentation covers API references, theme tutorials, and best practice guides updated regularly as the platform evolves.

Stencil GitHub repositories provide example implementations and issue tracking. Review closed issues to learn how others solved similar problems, and check open issues to avoid known bugs in your implementation.

BigCommerce Community forums connect you with other developers facing similar challenges. Search existing threads before posting new questions, and contribute solutions when you’ve solved problems others might encounter.

Development Tools and Extensions

Visual Studio Code extensions enhance productivity with Handlebars syntax highlighting, template autocomplete, and integrated terminal access for Stencil CLI commands. Configure your editor with linting rules that match Stencil coding standards.

Browser DevTools extensions for performance profiling help identify bottlenecks in custom code. Use Network panel for asset loading analysis and Performance panel for JavaScript execution profiling.

Version control through Git enables safe experimentation and team collaboration. Maintain separate branches for features, establish clear commit message conventions, and use pull requests for code review.

Testing and Debugging Tools

Stencil CLI includes debugging capabilities through verbose logging flags. Run stencil start –verbose to see detailed output about template compilation, asset bundling, and API requests.

Browser-based debugging tools reveal JavaScript errors and template rendering issues. Use breakpoints in DevTools to step through custom script execution and inspect variable state.

Automated testing frameworks like Jest enable unit testing for custom JavaScript modules. While template testing remains challenging, covering business logic with tests prevents regressions as code evolves.

Common Challenges and Solutions in Stencil Development

Even experienced developers encounter obstacles when building with Stencil BigCommerce. Recognizing common issues accelerates problem-solving.

Template Compilation Errors

Malformed Handlebars syntax causes compilation failures that prevent theme preview. Check for unclosed tags, mismatched helpers, and incorrect variable references. The Stencil CLI error messages usually point to the problematic template and line number.

Context mismatches occur when templates reference data not available on that page. Review front matter configuration to ensure necessary data queries execute, or adjust template logic to handle missing data gracefully.

Custom helper registration failures prevent templates from accessing needed functionality. Verify helper functions register correctly in global.js and that helper names don’t conflict with built-in helpers.

Performance Bottlenecks

Excessive API calls slow page loads and may trigger rate limiting. Combine related queries in front matter rather than making separate requests per component. Cache responses in JavaScript when data doesn’t change frequently.

Large JavaScript bundles increase parse and execution time. Code split by route and lazy load non-critical features. Remove unused dependencies that add weight without providing value.

Unoptimized images represent the most common performance issue. Implement responsive images with appropriate sizing, use next-gen formats where browser support allows, and compress all image assets.

Cross-Browser Compatibility Issues

CSS grid and flexbox implementations vary slightly across browsers. Test layouts in target browsers and use appropriate fallbacks for older browser versions your audience uses.

JavaScript API differences require polyfills for newer features. Include necessary polyfills only for browsers in your target support matrix to avoid unnecessary code weight.

Font rendering inconsistencies affect visual appearance across operating systems. Set appropriate font-display values and test typography on both Mac and Windows systems.

Debugging Theme Customization Issues

The theme editor sometimes caches old values, making testing difficult. Clear browser cache and hard refresh after saving theme settings. If issues persist, verify schema.json defines settings correctly.

Custom CSS specificity conflicts cause styling issues where theme editor changes don’t apply as expected. Use browser DevTools to inspect element styles and identify which rules take precedence.

Merchant-added scripts through Script Manager may conflict with theme functionality. Disable third-party scripts temporarily to isolate whether issues stem from theme code or external scripts.

Key Takeaways

• BigCommerce Stencil provides modern architecture for building flexible, performant e-commerce storefronts with responsive design and developer-friendly tools
• Successful theme development requires understanding Handlebars templating, modular component structure, and strategic API integration for dynamic functionality
• Blueprint to Stencil migration demands methodical planning, careful template conversion, and comprehensive testing to preserve functionality and SEO value
• Advanced techniques like custom widgets, Storefront API usage, and performance optimization separate basic implementations from expert-level Stencil development
• Knowing when to hire specialized developers and which tools to leverage accelerates project delivery and improves outcome quality

Conclusion

Mastering BigCommerce Stencil unlocks powerful customization capabilities that directly impact user experience, conversion rates, and long-term platform scalability. Whether you’re building themes from scratch, migrating from Blueprint, or extending existing functionality, understanding Stencil’s architecture and best practices ensures your development efforts deliver measurable business results.

The investment in Stencil expertise pays dividends through faster development cycles, better performance, and more maintainable code that evolves with your business needs. Ready to take your BigCommerce store to the next level with custom Stencil development? Contact our BigCommerce experts to discuss your project requirements and explore how strategic theme development drives e-commerce success.

Frequently Asked Questions

What Is the Difference Between BigCommerce Stencil and Blueprint?

Stencil is BigCommerce’s modern theme framework launched in 2016, featuring Handlebars templating, responsive design tools, and local development support. Blueprint is the legacy framework with PHP-based templates, limited mobile optimization, and no local testing capabilities. Stencil offers significantly better performance, easier customization, and merchant-friendly theme editing compared to Blueprint’s rigid structure.

How Long Does a BigCommerce Blueprint to Stencil Migration Take?

Most Blueprint to Stencil migrations require 6 to 12 weeks depending on customization complexity and store size. Simple migrations with minimal custom features may complete in 4 weeks, while heavily customized stores with extensive third-party integrations can take 16 weeks or longer. Timeline includes assessment, development, testing, and post-launch optimization phases.

Can I Customize BigCommerce Stencil Themes Without Coding Experience?

BigCommerce provides a Theme Editor that allows non-technical users to modify colors, fonts, layout options, and content without writing code. However, structural changes, custom features, and advanced design modifications require Handlebars, CSS, and JavaScript knowledge. Most merchants use the Theme Editor for basic adjustments and hire developers for substantive customizations.

What Programming Languages Do I Need to Know for Stencil Development?

Stencil development requires HTML, CSS (specifically SCSS), JavaScript, and Handlebars templating language. Familiarity with Node.js helps with local development environment setup and build tools. Understanding REST APIs and GraphQL is beneficial for Storefront API integration. No backend programming is required since BigCommerce handles server-side functionality.

Does Migrating to Stencil Affect My Store’s SEO Rankings?

A properly executed migration preserves SEO value when you maintain URL structure, meta data, and on-page optimization elements. Stencil’s improved performance actually benefits SEO through better Core Web Vitals scores. However, poor migration planning that changes URLs without proper redirects or loses content can harm rankings. Always implement redirects, verify structured data, and test thoroughly before launching.

How Much Does It Cost to Hire a BigCommerce Stencil Developer?

Freelance Stencil developers typically charge $75 to $150 per hour depending on experience and location. Agencies range from $100 to $200+ per hour but provide team expertise and project management. Complete custom theme development costs $15,000 to $50,000, while Blueprint migrations range from $10,000 to $30,000 based on complexity. Simple customizations may cost $2,000 to $5,000.

Can I Use Multiple Stencil Themes on One BigCommerce Store?

BigCommerce allows one active theme per storefront, though you can install multiple themes and switch between them. The platform supports channel-specific themes if you operate multiple storefronts under one account. Most merchants maintain one primary theme and use the Theme Editor to create seasonal variations rather than managing multiple complete themes.

What Are the Performance Benefits of Stencil Over Blueprint?

Stencil delivers 30 to 50 percent faster page loads through optimized asset bundling, lazy loading, and efficient JavaScript execution. The framework’s Webpack compilation eliminates unused code, while responsive image handling reduces mobile payload. Stencil themes typically score 20 to 30 points higher on Google Lighthouse compared to equivalent Blueprint implementations due to modern performance optimizations.

Source: https://ecommerce.folio3.com/blog/bigcommerce-stencil-guide-to-theme-customization/

---

You might also like this video