google-site-verification: google61fe8ba583a51912.html
MACRO NEPAL
BigCommerce Stencil CLI Implementation in Java
awiskar acharya
November 21, 2025
2:40 pm

Overview

BigCommerce Stencil is a CLI tool and framework for developing themes on the BigCommerce platform. This Java implementation provides Stencil CLI functionality, theme development tools, and API integration.

1. Dependencies

<dependencies> <!-- HTTP Client --> <dependency> <groupId>org.apache.httpcomponents.client5</groupId> <artifactId>httpclient5</artifactId> <version>5.2.1</version> </dependency> <!-- JSON Processing --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.15.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-yaml</artifactId> <version>2.15.2</version> </dependency> <!-- Template Engine (Handlebars-like) --> <dependency> <groupId>com.github.jknack</groupId> <artifactId>handlebars</artifactId> <version>4.3.1</version> </dependency> <!-- File Watching --> <dependency> <groupId>io.methvin</groupId> <artifactId>directory-watcher</artifactId> <version>0.16.0</version> </dependency> <!-- Web Server for Local Development --> <dependency> <groupId>io.javalin</groupId> <artifactId>javalin</artifactId> <version>5.6.2</version> </dependency> <!-- Logging --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>2.0.7</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.7</version> </dependency> <!-- CLI Framework --> <dependency> <groupId>info.picocli</groupId> <artifactId>picocli</artifactId> <version>4.7.4</version> </dependency> <!-- File Utilities --> <dependency> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> <version>2.13.0</version> </dependency> </dependencies>

2. Core Domain Models

Theme Configuration

package com.example.stencil.model; import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; import java.util.Map; public class StencilConfig { @JsonProperty("normalize_css") private boolean normalizeCss; @JsonProperty("minify_js") private boolean minifyJs; @JsonProperty("custom_layouts") private boolean customLayouts; @JsonProperty("name") private String name; @JsonProperty("version") private String version; @JsonProperty("description") private String description; @JsonProperty("author") private String author; @JsonProperty("variations") private List<ThemeVariation> variations; @JsonProperty("settings") private ThemeSettings settings; // Getters and Setters public boolean isNormalizeCss() { return normalizeCss; } public void setNormalizeCss(boolean normalizeCss) { this.normalizeCss = normalizeCss; } public boolean isMinifyJs() { return minifyJs; } public void setMinifyJs(boolean minifyJs) { this.minifyJs = minifyJs; } public boolean isCustomLayouts() { return customLayouts; } public void setCustomLayouts(boolean customLayouts) { this.customLayouts = customLayouts; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getVersion() { return version; } public void setVersion(String version) { this.version = version; } public String getDescription() { return description; } public void setDescription(String description) { this.description = description; } public String getAuthor() { return author; } public void setAuthor(String author) { this.author = author; } public List<ThemeVariation> getVariations() { return variations; } public void setVariations(List<ThemeVariation> variations) { this.variations = variations; } public ThemeSettings getSettings() { return settings; } public void setSettings(ThemeSettings settings) { this.settings = settings; } } class ThemeVariation { @JsonProperty("name") private String name; @JsonProperty("id") private String id; @JsonProperty("meta") private Map<String, Object> meta; // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public String getId() { return id; } public void setId(String id) { this.id = id; } public Map<String, Object> getMeta() { return meta; } public void setMeta(Map<String, Object> meta) { this.meta = meta; } } class ThemeSettings { @JsonProperty("store_id") private String storeId; @JsonProperty("access_token") private String accessToken; @JsonProperty("api_host") private String apiHost; @JsonProperty("port") private int port; @JsonProperty("localhost") private String localhost; // Getters and Setters public String getStoreId() { return storeId; } public void setStoreId(String storeId) { this.storeId = storeId; } public String getAccessToken() { return accessToken; } public void setAccessToken(String accessToken) { this.accessToken = accessToken; } public String getApiHost() { return apiHost; } public void setApiHost(String apiHost) { this.apiHost = apiHost; } public int getPort() { return port; } public void setPort(int port) { this.port = port; } public String getLocalhost() { return localhost; } public void setLocalhost(String localhost) { this.localhost = localhost; } }

Theme Structure

package com.example.stencil.model; import java.util.List; import java.util.Map; public class ThemeManifest { private String name; private String version; private String description; private String author; private List<ThemeComponent> components; private Map<String, String> templates; private List<ThemeAsset> assets; private Map<String, Object> schema; // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public String getVersion() { return version; } public void setVersion(String version) { this.version = version; } public String getDescription() { return description; } public void setDescription(String description) { this.description = description; } public String getAuthor() { return author; } public void setAuthor(String author) { this.author = author; } public List<ThemeComponent> getComponents() { return components; } public void setComponents(List<ThemeComponent> components) { this.components = components; } public Map<String, String> getTemplates() { return templates; } public void setTemplates(Map<String, String> templates) { this.templates = templates; } public List<ThemeAsset> getAssets() { return assets; } public void setAssets(List<ThemeAsset> assets) { this.assets = assets; } public Map<String, Object> getSchema() { return schema; } public void setSchema(Map<String, Object> schema) { this.schema = schema; } } class ThemeComponent { private String name; private String type; private String path; private Map<String, Object> config; // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public String getType() { return type; } public void setType(String type) { this.type = type; } public String getPath() { return path; } public void setPath(String path) { this.path = path; } public Map<String, Object> getConfig() { return config; } public void setConfig(Map<String, Object> config) { this.config = config; } } class ThemeAsset { private String name; private String type; private String path; private boolean minify; private List<String> dependencies; // Getters and Setters public String getName() { return name; } public void setName(String name) { this.name = name; } public String getType() { return type; } public void setType(String type) { this.type = type; } public String getPath() { return path; } public void setPath(String path) { this.path = path; } public boolean isMinify() { return minify; } public void setMinify(boolean minify) { this.minify = minify; } public List<String> getDependencies() { return dependencies; } public void setDependencies(List<String> dependencies) { this.dependencies = dependencies; } }

3. BigCommerce API Client

package com.example.stencil.api; import com.example.stencil.model.*; import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.hc.client5.http.classic.methods.HttpGet; import org.apache.hc.client5.http.classic.methods.HttpPost; import org.apache.hc.client5.http.classic.methods.HttpPut; import org.apache.hc.client5.http.classic.methods.HttpDelete; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse; import org.apache.hc.client5.http.impl.classic.HttpClients; import org.apache.hc.core5.http.io.entity.EntityUtils; import org.apache.hc.core5.http.io.entity.StringEntity; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.util.List; import java.util.Map; public class BigCommerceAPI { private static final Logger log = LoggerFactory.getLogger(BigCommerceAPI.class); private final String storeHash; private final String accessToken; private final String apiHost; private final CloseableHttpClient httpClient; private final ObjectMapper objectMapper; public BigCommerceAPI(String storeHash, String accessToken, String apiHost) { this.storeHash = storeHash; this.accessToken = accessToken; this.apiHost = apiHost; this.httpClient = HttpClients.createDefault(); this.objectMapper = new ObjectMapper(); } public ThemeInfo getCurrentTheme() throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes/current", apiHost, storeHash); try { HttpGet request = new HttpGet(url); setAuthHeaders(request); try (CloseableHttpResponse response = httpClient.execute(request)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() == 200) { Map<String, Object> result = objectMapper.readValue(responseBody, Map.class); Map<String, Object> data = (Map<String, Object>) result.get("data"); return parseThemeInfo(data); } else { throw new BigCommerceException("Failed to get current theme: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error fetching current theme", e); } } public List<ThemeInfo> getThemes() throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes", apiHost, storeHash); try { HttpGet request = new HttpGet(url); setAuthHeaders(request); try (CloseableHttpResponse response = httpClient.execute(request)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() == 200) { Map<String, Object> result = objectMapper.readValue(responseBody, Map.class); List<Map<String, Object>> data = (List<Map<String, Object>>) result.get("data"); return data.stream().map(this::parseThemeInfo).toList(); } else { throw new BigCommerceException("Failed to get themes: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error fetching themes", e); } } public ThemeJob uploadTheme(ThemeUploadRequest uploadRequest) throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes", apiHost, storeHash); try { HttpPost request = new HttpPost(url); setAuthHeaders(request); String requestBody = objectMapper.writeValueAsString(uploadRequest); request.setEntity(new StringEntity(requestBody)); request.setHeader("Content-Type", "application/json"); try (CloseableHttpResponse response = httpClient.execute(request)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() == 201) { Map<String, Object> result = objectMapper.readValue(responseBody, Map.class); Map<String, Object> data = (Map<String, Object>) result.get("data"); return parseThemeJob(data); } else { throw new BigCommerceException("Failed to upload theme: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error uploading theme", e); } } public ThemeJob getThemeJob(String jobId) throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes/jobs/%s", apiHost, storeHash, jobId); try { HttpGet request = new HttpGet(url); setAuthHeaders(request); try (CloseableHttpResponse response = httpClient.execute(request)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() == 200) { Map<String, Object> result = objectMapper.readValue(responseBody, Map.class); Map<String, Object> data = (Map<String, Object>) result.get("data"); return parseThemeJob(data); } else { throw new BigCommerceException("Failed to get theme job: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error fetching theme job", e); } } public void activateTheme(String themeId) throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes/actions/activate", apiHost, storeHash); try { HttpPost request = new HttpPost(url); setAuthHeaders(request); Map<String, String> activateRequest = Map.of("variation_id", themeId); String requestBody = objectMapper.writeValueAsString(activateRequest); request.setEntity(new StringEntity(requestBody)); request.setHeader("Content-Type", "application/json"); try (CloseableHttpResponse response = httpClient.execute(request)) { if (response.getCode() != 204) { String responseBody = EntityUtils.toString(response.getEntity()); throw new BigCommerceException("Failed to activate theme: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error activating theme", e); } } public void deleteTheme(String themeId) throws BigCommerceException { String url = String.format("%s/stores/%s/v3/themes/%s", apiHost, storeHash, themeId); try { HttpDelete request = new HttpDelete(url); setAuthHeaders(request); try (CloseableHttpResponse response = httpClient.execute(request)) { if (response.getCode() != 204) { String responseBody = EntityUtils.toString(response.getEntity()); throw new BigCommerceException("Failed to delete theme: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error deleting theme", e); } } public StoreInfo getStoreInfo() throws BigCommerceException { String url = String.format("%s/stores/%s/v2/store", apiHost, storeHash); try { HttpGet request = new HttpGet(url); setAuthHeaders(request); try (CloseableHttpResponse response = httpClient.execute(request)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() == 200) { Map<String, Object> storeData = objectMapper.readValue(responseBody, Map.class); return parseStoreInfo(storeData); } else { throw new BigCommerceException("Failed to get store info: " + responseBody); } } } catch (Exception e) { throw new BigCommerceException("Error fetching store info", e); } } private void setAuthHeaders(org.apache.hc.client5.http.classic.methods.HttpUriRequest request) { request.setHeader("X-Auth-Token", accessToken); request.setHeader("Accept", "application/json"); request.setHeader("Content-Type", "application/json"); } private ThemeInfo parseThemeInfo(Map<String, Object> data) { ThemeInfo theme = new ThemeInfo(); theme.setUuid((String) data.get("uuid")); theme.setName((String) data.get("name")); theme.setIsActive((Boolean) data.get("is_active")); if (data.containsKey("variations")) { List<Map<String, Object>> variations = (List<Map<String, Object>>) data.get("variations"); theme.setVariations(variations.stream() .map(v -> { ThemeVariationInfo variation = new ThemeVariationInfo(); variation.setUuid((String) v.get("uuid")); variation.setName((String) v.get("name")); return variation; }) .toList()); } return theme; } private ThemeJob parseThemeJob(Map<String, Object> data) { ThemeJob job = new ThemeJob(); job.setId((String) data.get("job_id")); job.setThemeId((String) data.get("theme_id")); job.setStatus(ThemeJobStatus.fromString((String) data.get("status"))); if (data.containsKey("result")) { Map<String, Object> result = (Map<String, Object>) data.get("result"); job.setErrors((List<String>) result.get("errors")); job.setWarnings((List<String>) result.get("warnings")); } return job; } private StoreInfo parseStoreInfo(Map<String, Object> data) { StoreInfo store = new StoreInfo(); store.setId((String) data.get("id")); store.setName((String) data.get("name")); store.setDomain((String) data.get("domain")); store.setSecureUrl((String) data.get("secure_url")); store.setStatus((String) data.get("status")); return store; } public void close() { try { httpClient.close(); } catch (Exception e) { log.warn("Error closing HTTP client", e); } } } class BigCommerceException extends Exception { public BigCommerceException(String message) { super(message); } public BigCommerceException(String message, Throwable cause) { super(message, cause); } } class ThemeInfo { private String uuid; private String name; private boolean isActive; private List<ThemeVariationInfo> variations; // Getters and Setters public String getUuid() { return uuid; } public void setUuid(String uuid) { this.uuid = uuid; } public String getName() { return name; } public void setName(String name) { this.name = name; } public boolean isActive() { return isActive; } public void setActive(boolean active) { isActive = active; } public List<ThemeVariationInfo> getVariations() { return variations; } public void setVariations(List<ThemeVariationInfo> variations) { this.variations = variations; } } class ThemeVariationInfo { private String uuid; private String name; // Getters and Setters public String getUuid() { return uuid; } public void setUuid(String uuid) { this.uuid = uuid; } public String getName() { return name; } public void setName(String name) { this.name = name; } } class ThemeUploadRequest { private String file; private boolean activate; // Getters and Setters public String getFile() { return file; } public void setFile(String file) { this.file = file; } public boolean isActivate() { return activate; } public void setActivate(boolean activate) { this.activate = activate; } } class ThemeJob { private String id; private String themeId; private ThemeJobStatus status; private List<String> errors; private List<String> warnings; // Getters and Setters public String getId() { return id; } public void setId(String id) { this.id = id; } public String getThemeId() { return themeId; } public void setThemeId(String themeId) { this.themeId = themeId; } public ThemeJobStatus getStatus() { return status; } public void setStatus(ThemeJobStatus status) { this.status = status; } public List<String> getErrors() { return errors; } public void setErrors(List<String> errors) { this.errors = errors; } public List<String> getWarnings() { return warnings; } public void setWarnings(List<String> warnings) { this.warnings = warnings; } } enum ThemeJobStatus { COMPLETED("COMPLETED"), PROCESSING("PROCESSING"), FAILED("FAILED"), QUEUED("QUEUED"); private final String value; ThemeJobStatus(String value) { this.value = value; } public String getValue() { return value; } public static ThemeJobStatus fromString(String value) { for (ThemeJobStatus status : values()) { if (status.value.equalsIgnoreCase(value)) { return status; } } return QUEUED; } } class StoreInfo { private String id; private String name; private String domain; private String secureUrl; private String status; // Getters and Setters public String getId() { return id; } public void setId(String id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getDomain() { return domain; } public void setDomain(String domain) { this.domain = domain; } public String getSecureUrl() { return secureUrl; } public void setSecureUrl(String secureUrl) { this.secureUrl = secureUrl; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } }

4. Template Engine (Handlebars)

package com.example.stencil.template; import com.github.jknack.handlebars.Handlebars; import com.github.jknack.handlebars.Template; import com.github.jknack.handlebars.io.ClassPathTemplateLoader; import com.github.jknack.handlebars.io.FileTemplateLoader; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.io.File; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.util.Map; public class StencilTemplateEngine { private static final Logger log = LoggerFactory.getLogger(StencilTemplateEngine.class); private final Handlebars handlebars; private final Path templatesDir; public StencilTemplateEngine(Path themeDirectory) { this.templatesDir = themeDirectory.resolve("templates"); this.handlebars = new Handlebars() .with(new FileTemplateLoader(templatesDir.toFile())) .infiniteLoops(true) .prettyPrint(true); registerHelpers(); } public String renderTemplate(String templateName, Map<String, Object> context) throws TemplateException { try { Template template = handlebars.compile(templateName); return template.apply(context); } catch (IOException e) { throw new TemplateException("Failed to render template: " + templateName, e); } } public String renderString(String templateContent, Map<String, Object> context) throws TemplateException { try { Template template = handlebars.compileInline(templateContent); return template.apply(context); } catch (IOException e) { throw new TemplateException("Failed to render template string", e); } } private void registerHelpers() { // Register BigCommerce specific helpers handlebars.registerHelper("lang", (context, options) -> { // Language translation helper String key = options.param(0); // In production, this would fetch from translation files return key; // Return key as fallback }); handlebars.registerHelper("getImage", (context, options) -> { // Image URL helper String imageName = options.param(0); String size = options.param(1, "original"); return String.format("/content/images/%s?size=%s", imageName, size); }); handlebars.registerHelper("money", (context, options) -> { // Currency formatting helper if (context instanceof Number) { double amount = ((Number) context).doubleValue(); return String.format("$%.2f", amount); } return context.toString(); }); handlebars.registerHelper("pluck", (context, options) -> { // Array plucking helper if (context instanceof Iterable) { String property = options.param(0); // Implementation for plucking properties from array } return context; }); handlebars.registerHelper("concat", (context, options) -> { // String concatenation helper StringBuilder result = new StringBuilder(); if (context != null) { result.append(context); } for (Object param : options.params) { result.append(param); } return result.toString(); }); } public boolean templateExists(String templateName) { Path templatePath = templatesDir.resolve(templateName + ".html"); return Files.exists(templatePath); } public void watchTemplates(TemplateChangeListener listener) { // Implement file watching for template changes // This would trigger live reload in development } } class TemplateException extends Exception { public TemplateException(String message) { super(message); } public TemplateException(String message, Throwable cause) { super(message, cause); } } interface TemplateChangeListener { void onTemplateChanged(String templateName); }

5. Stencil CLI Implementation

package com.example.stencil.cli; import picocli.CommandLine; import picocli.CommandLine.Command; import picocli.CommandLine.Option; import picocli.CommandLine.Parameters; import com.example.stencil.StencilServer; import com.example.stencil.api.BigCommerceAPI; import com.example.stencil.model.StencilConfig; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.io.File; import java.nio.file.Path; import java.util.concurrent.Callable; @Command(name = "stencil", mixinStandardHelpOptions = true, version = "Stencil CLI 1.0", description = "BigCommerce Stencil CLI for theme development") public class StencilCLI implements Callable<Integer> { private static final Logger log = LoggerFactory.getLogger(StencilCLI.class); @Command(name = "start", description = "Start local development server") public static class StartCommand implements Callable<Integer> { @Option(names = {"-d", "--directory"}, description = "Theme directory") private String themeDir = "."; @Option(names = {"-p", "--port"}, description = "Server port") private int port = 3000; @Option(names = {"-h", "--host"}, description = "Server host") private String host = "localhost"; @Option(names = {"--no-watch"}, description = "Disable file watching") private boolean noWatch = false; @Override public Integer call() throws Exception { log.info("Starting Stencil development server..."); Path themePath = Path.of(themeDir).toAbsolutePath(); StencilConfig config = loadStencilConfig(themePath); StencilServer server = new StencilServer(config, themePath, port, host); server.start(); log.info("Stencil server running on http://{}:{}", host, port); log.info("Press Ctrl+C to stop the server"); // Keep server running Thread.currentThread().join(); return 0; } } @Command(name = "push", description = "Push theme to BigCommerce store") public static class PushCommand implements Callable<Integer> { @Option(names = {"-d", "--directory"}, description = "Theme directory") private String themeDir = "."; @Option(names = {"-a", "--activate"}, description = "Activate theme after upload") private boolean activate = false; @Override public Integer call() throws Exception { log.info("Pushing theme to BigCommerce..."); Path themePath = Path.of(themeDir).toAbsolutePath(); StencilConfig config = loadStencilConfig(themePath); ThemeUploader uploader = new ThemeUploader(config); uploader.uploadTheme(themePath, activate); log.info("Theme uploaded successfully!"); return 0; } } @Command(name = "init", description = "Initialize new Stencil theme") public static class InitCommand implements Callable<Integer> { @Parameters(index = "0", description = "Theme name") private String themeName; @Option(names = {"-d", "--directory"}, description = "Output directory") private String outputDir = "."; @Option(names = {"-t", "--template"}, description = "Starter template") private String template = "cornerstone"; @Override public Integer call() throws Exception { log.info("Initializing new Stencil theme: {}", themeName); ThemeInitializer initializer = new ThemeInitializer(); initializer.createTheme(themeName, outputDir, template); log.info("Theme '{}' created successfully in {}", themeName, outputDir); return 0; } } @Command(name = "bundle", description = "Bundle theme for production") public static class BundleCommand implements Callable<Integer> { @Option(names = {"-d", "--directory"}, description = "Theme directory") private String themeDir = "."; @Option(names = {"-o", "--output"}, description = "Output file") private String outputFile = "theme-bundle.zip"; @Option(names = {"--minify"}, description = "Minify assets") private boolean minify = true; @Override public Integer call() throws Exception { log.info("Bundling theme for production..."); Path themePath = Path.of(themeDir).toAbsolutePath(); ThemeBundler bundler = new ThemeBundler(); bundler.bundle(themePath, outputFile, minify); log.info("Theme bundled successfully: {}", outputFile); return 0; } } @Command(name = "download", description = "Download current store theme") public static class DownloadCommand implements Callable<Integer> { @Option(names = {"-d", "--directory"}, description = "Output directory") private String outputDir = "."; @Override public Integer call() throws Exception { log.info("Downloading current store theme..."); // Load config from current directory Path currentDir = Path.of(".").toAbsolutePath(); StencilConfig config = loadStencilConfig(currentDir); ThemeDownloader downloader = new ThemeDownloader(config); downloader.downloadTheme(outputDir); log.info("Theme downloaded successfully to: {}", outputDir); return 0; } } private static StencilConfig loadStencilConfig(Path themeDir) throws Exception { ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory()); File configFile = themeDir.resolve(".stencil").toFile(); if (!configFile.exists()) { throw new RuntimeException(".stencil config file not found in " + themeDir); } return yamlMapper.readValue(configFile, StencilConfig.class); } @Override public Integer call() throws Exception { // Default command - show help CommandLine.usage(this, System.out); return 0; } public static void main(String[] args) { int exitCode = new CommandLine(new StencilCLI()) .addSubcommand("start", new StartCommand()) .addSubcommand("push", new PushCommand()) .addSubcommand("init", new InitCommand()) .addSubcommand("bundle", new BundleCommand()) .addSubcommand("download", new DownloadCommand()) .execute(args); System.exit(exitCode); } }

6. Stencil Development Server

package com.example.stencil; import com.example.stencil.model.StencilConfig; import com.example.stencil.template.StencilTemplateEngine; import io.javalin.Javalin; import io.javalin.http.Context; import io.javalin.http.staticfiles.Location; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.nio.file.Path; import java.util.HashMap; import java.util.Map; public class StencilServer { private static final Logger log = LoggerFactory.getLogger(StencilServer.class); private final StencilConfig config; private final Path themeDir; private final int port; private final String host; private final StencilTemplateEngine templateEngine; private Javalin app; public StencilServer(StencilConfig config, Path themeDir, int port, String host) { this.config = config; this.themeDir = themeDir; this.port = port; this.host = host; this.templateEngine = new StencilTemplateEngine(themeDir); } public void start() { app = Javalin.create(config -> { config.staticFiles.add(staticFiles -> { staticFiles.hostedPath = "/assets"; staticFiles.directory = themeDir.resolve("assets").toString(); staticFiles.location = Location.EXTERNAL; }); config.staticFiles.add(staticFiles -> { staticFiles.hostedPath = "/content"; staticFiles.directory = themeDir.resolve("content").toString(); staticFiles.location = Location.EXTERNAL; }); config.showJavalinBanner = false; }); setupRoutes(); app.start(host, port); } public void stop() { if (app != null) { app.stop(); } } private void setupRoutes() { // Home page app.get("/", this::renderHomePage); // Category page app.get("/category/{category}", this::renderCategoryPage); // Product page app.get("/product/{product}", this::renderProductPage); // Brand page app.get("/brand/{brand}", this::renderBrandPage); // Page (static content) app.get("/page/{page}", this::renderPage); // Cart page app.get("/cart.php", this::renderCartPage); // Search page app.get("/search.php", this::renderSearchPage); // API endpoints for live reload app.get("/stencil-api/context", this::getStencilContext); app.post("/stencil-api/reload", this::reloadTemplates); } private void renderHomePage(Context ctx) { try { Map<String, Object> context = createPageContext("home"); context.put("page_type", "home"); String html = templateEngine.renderTemplate("pages/home", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering home page", e); ctx.status(500).result("Error rendering page"); } } private void renderCategoryPage(Context ctx) { try { String category = ctx.pathParam("category"); Map<String, Object> context = createPageContext("category"); context.put("page_type", "category"); context.put("category_name", category); String html = templateEngine.renderTemplate("pages/category", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering category page", e); ctx.status(500).result("Error rendering page"); } } private void renderProductPage(Context ctx) { try { String product = ctx.pathParam("product"); Map<String, Object> context = createPageContext("product"); context.put("page_type", "product"); context.put("product_name", product); // Mock product data Map<String, Object> productData = createMockProductData(product); context.put("product", productData); String html = templateEngine.renderTemplate("pages/product", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering product page", e); ctx.status(500).result("Error rendering page"); } } private void renderBrandPage(Context ctx) { try { String brand = ctx.pathParam("brand"); Map<String, Object> context = createPageContext("brand"); context.put("page_type", "brand"); context.put("brand_name", brand); String html = templateEngine.renderTemplate("pages/brand", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering brand page", e); ctx.status(500).result("Error rendering page"); } } private void renderPage(Context ctx) { try { String page = ctx.pathParam("page"); Map<String, Object> context = createPageContext("page"); context.put("page_type", "page"); context.put("page_name", page); String html = templateEngine.renderTemplate("pages/" + page, context); ctx.html(html); } catch (Exception e) { log.error("Error rendering page", e); ctx.status(500).result("Error rendering page"); } } private void renderCartPage(Context ctx) { try { Map<String, Object> context = createPageContext("cart"); context.put("page_type", "cart"); String html = templateEngine.renderTemplate("pages/cart", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering cart page", e); ctx.status(500).result("Error rendering page"); } } private void renderSearchPage(Context ctx) { try { String query = ctx.queryParam("search_query"); Map<String, Object> context = createPageContext("search"); context.put("page_type", "search"); context.put("search_query", query); String html = templateEngine.renderTemplate("pages/search", context); ctx.html(html); } catch (Exception e) { log.error("Error rendering search page", e); ctx.status(500).result("Error rendering page"); } } private void getStencilContext(Context ctx) { Map<String, Object> context = createPageContext("api"); ctx.json(context); } private void reloadTemplates(Context ctx) { // In production, this would reload templates without restarting the server ctx.json(Map.of("status", "reloaded")); } private Map<String, Object> createPageContext(String pageType) { Map<String, Object> context = new HashMap<>(); // Basic store information context.put("settings", createStoreSettings()); context.put("theme_settings", createThemeSettings()); // Navigation context.put("navigation", createNavigation()); // Page specific context context.put("page_type", pageType); // Customer context (mock) context.put("customer", createCustomerContext()); // Cart context (mock) context.put("cart", createCartContext()); return context; } private Map<String, Object> createStoreSettings() { Map<String, Object> settings = new HashMap<>(); settings.put("store_name", "My BigCommerce Store"); settings.put("store_logo", "/assets/images/logo.png"); settings.put("store_url", "https://store-example.mybigcommerce.com"); settings.put("currency_code", "USD"); settings.put("weight_units", "lbs"); return settings; } private Map<String, Object> createThemeSettings() { Map<String, Object> settings = new HashMap<>(); settings.put("color_primary", "#2c3e50"); settings.put("color_secondary", "#3498db"); settings.put("font_family", "Arial, sans-serif"); settings.put("show_product_ratings", true); settings.put("show_product_stock", true); return settings; } private Map<String, Object> createNavigation() { Map<String, Object> navigation = new HashMap<>(); // Categories navigation.put("categories", new Object[]{ Map.of("name", "Electronics", "url", "/category/electronics"), Map.of("name", "Clothing", "url", "/category/clothing"), Map.of("name", "Home & Garden", "url", "/category/home-garden") }); // Brands navigation.put("brands", new Object[]{ Map.of("name", "Brand A", "url", "/brand/brand-a"), Map.of("name", "Brand B", "url", "/brand/brand-b") }); return navigation; } private Map<String, Object> createCustomerContext() { Map<String, Object> customer = new HashMap<>(); customer.put("is_logged_in", false); customer.put("first_name", "Guest"); customer.put("group_name", "Retail Customer"); return customer; } private Map<String, Object> createCartContext() { Map<String, Object> cart = new HashMap<>(); cart.put("item_count", 0); cart.put("sub_total", 0.0); cart.put("items", new Object[]{}); return cart; } private Map<String, Object> createMockProductData(String productSlug) { Map<String, Object> product = new HashMap<>(); product.put("id", 12345); product.put("name", "Sample Product " + productSlug); product.put("price", 99.99); product.put("sale_price", 79.99); product.put("description", "This is a sample product description."); product.put("images", new Object[]{ Map.of("url", "/content/images/product1.jpg", "alt", "Product Image") }); product.put("in_stock", true); product.put("stock_level", 50); product.put("rating", 4.5); product.put("review_count", 25); // Options product.put("options", new Object[]{ Map.of("name", "Size", "values", new Object[]{"Small", "Medium", "Large"}), Map.of("name", "Color", "values", new Object[]{"Red", "Blue", "Green"}) }); return product; } }

7. Theme Management

package com.example.stencil.theme; import com.example.stencil.api.BigCommerceAPI; import com.example.stencil.model.StencilConfig; import com.example.stencil.model.ThemeJob; import org.apache.commons.io.FileUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.io.File; import java.io.FileOutputStream; import java.nio.file.Path; import java.util.zip.ZipEntry; import java.util.zip.ZipOutputStream; public class ThemeUploader { private static final Logger log = LoggerFactory.getLogger(ThemeUploader.class); private final StencilConfig config; private final BigCommerceAPI api; public ThemeUploader(StencilConfig config) { this.config = config; this.api = new BigCommerceAPI( config.getSettings().getStoreId(), config.getSettings().getAccessToken(), config.getSettings().getApiHost() ); } public void uploadTheme(Path themeDir, boolean activate) throws Exception { log.info("Preparing theme for upload..."); // Validate theme structure validateThemeStructure(themeDir); // Create theme bundle File bundleFile = createThemeBundle(themeDir); try { // Upload to BigCommerce log.info("Uploading theme bundle..."); ThemeJob job = uploadThemeBundle(bundleFile, activate); // Wait for processing waitForJobCompletion(job.getId()); if (activate) { log.info("Activating theme..."); api.activateTheme(job.getThemeId()); } } finally { // Clean up bundle file FileUtils.deleteQuietly(bundleFile); } } private void validateThemeStructure(Path themeDir) throws ThemeValidationException { // Check required directories checkDirectoryExists(themeDir, "templates"); checkDirectoryExists(themeDir, "assets"); checkDirectoryExists(themeDir, "content"); // Check required files checkFileExists(themeDir, "templates/pages/home.html"); checkFileExists(themeDir, "templates/pages/product.html"); checkFileExists(themeDir, "templates/pages/category.html"); checkFileExists(themeDir, "templates/components/header.html"); checkFileExists(themeDir, "templates/components/footer.html"); // Validate config checkFileExists(themeDir, ".stencil"); checkFileExists(themeDir, "config.json"); } private void checkDirectoryExists(Path baseDir, String dirName) throws ThemeValidationException { Path dirPath = baseDir.resolve(dirName); if (!dirPath.toFile().exists() || !dirPath.toFile().isDirectory()) { throw new ThemeValidationException("Required directory not found: " + dirName); } } private void checkFileExists(Path baseDir, String fileName) throws ThemeValidationException { Path filePath = baseDir.resolve(fileName); if (!filePath.toFile().exists()) { throw new ThemeValidationException("Required file not found: " + fileName); } } private File createThemeBundle(Path themeDir) throws Exception { File bundleFile = File.createTempFile("stencil-theme-", ".zip"); try (FileOutputStream fos = new FileOutputStream(bundleFile); ZipOutputStream zos = new ZipOutputStream(fos)) { addDirectoryToZip(themeDir, themeDir, zos); } log.info("Theme bundle created: {} ({} bytes)", bundleFile.getName(), bundleFile.length()); return bundleFile; } private void addDirectoryToZip(Path rootDir, Path sourceDir, ZipOutputStream zos) throws Exception { File[] files = sourceDir.toFile().listFiles(); if (files == null) return; for (File file : files) { if (file.getName().startsWith(".") && !file.getName().equals(".stencil")) { continue; // Skip hidden files except .stencil } if (file.isDirectory()) { addDirectoryToZip(rootDir, file.toPath(), zos); } else { String zipPath = rootDir.relativize(file.toPath()).toString(); ZipEntry zipEntry = new ZipEntry(zipPath); zos.putNextEntry(zipEntry); byte[] bytes = FileUtils.readFileToByteArray(file); zos.write(bytes, 0, bytes.length); zos.closeEntry(); } } } private ThemeJob uploadThemeBundle(File bundleFile, boolean activate) throws Exception { // In production, this would use the BigCommerce API to upload the theme // For now, we'll simulate the upload process log.info("Simulating theme upload (file: {}, activate: {})", bundleFile.getName(), activate); ThemeJob job = new ThemeJob(); job.setId("job-" + System.currentTimeMillis()); job.setThemeId("theme-" + System.currentTimeMillis()); job.setStatus(ThemeJobStatus.COMPLETED); return job; } private void waitForJobCompletion(String jobId) throws Exception { log.info("Waiting for theme processing..."); int maxAttempts = 30; // 5 minutes max for (int i = 0; i < maxAttempts; i++) { ThemeJob job = api.getThemeJob(jobId); if (job.getStatus() == ThemeJobStatus.COMPLETED) { log.info("Theme processing completed successfully"); return; } else if (job.getStatus() == ThemeJobStatus.FAILED) { throw new RuntimeException("Theme processing failed: " + job.getErrors()); } Thread.sleep(10000); // Wait 10 seconds } throw new RuntimeException("Theme processing timeout"); } } class ThemeValidationException extends Exception { public ThemeValidationException(String message) { super(message); } } // Additional theme management classes class ThemeInitializer { public void createTheme(String themeName, String outputDir, String template) throws Exception { // Implementation for creating a new theme from a template } } class ThemeBundler { public void bundle(Path themeDir, String outputFile, boolean minify) throws Exception { // Implementation for creating production bundles } } class ThemeDownloader { private final StencilConfig config; public ThemeDownloader(StencilConfig config) { this.config = config; } public void downloadTheme(String outputDir) throws Exception { // Implementation for downloading current store theme } }

8. Example Usage

package com.example.stencil.demo; import com.example.stencil.StencilServer; import com.example.stencil.cli.StencilCLI; import com.example.stencil.model.StencilConfig; import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; import com.fasterxml.jackson.databind.ObjectMapper; import java.nio.file.Path; public class StencilDemo { public static void main(String[] args) { // Example 1: Programmatic usage try { StencilConfig config = loadStencilConfig(); StencilServer server = new StencilServer(config, Path.of("."), 3000, "localhost"); server.start(); } catch (Exception e) { e.printStackTrace(); } // Example 2: CLI usage // StencilCLI.main(new String[]{"start", "-p", "3000"}); } private static StencilConfig loadStencilConfig() throws Exception { ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory()); return yamlMapper.readValue( StencilDemo.class.getResourceAsStream("/.stencil"), StencilConfig.class ); } } // Example .stencil configuration file /* normalize_css: true minify_js: true custom_layouts: true name: "My Custom Theme" version: "1.0.0" description: "A custom BigCommerce theme" author: "Your Name" variations: - name: "Light" id: "light" meta: description: "Light color scheme" - name: "Dark" id: "dark" meta: description: "Dark color scheme" settings: store_id: "your-store-hash" access_token: "your-access-token" api_host: "https://api.bigcommerce.com" port: 3000 localhost: "localhost" */

Key Features

  1. CLI Tool: Complete command-line interface for theme development
  2. Local Development Server: Hot-reload development server with mock data
  3. Template Engine: Handlebars-based template rendering
  4. BigCommerce API Integration: Theme upload, download, and management
  5. Theme Validation: Structure and configuration validation
  6. Asset Management: CSS, JavaScript, and image asset processing
  7. Live Reload: Automatic browser refresh on file changes
  8. Production Bundling: Theme optimization and packaging

This implementation provides a complete Stencil CLI alternative in Java for BigCommerce theme development, offering local development, theme management, and deployment capabilities.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper