Installation and local development — kingsbell Documentation

kingsbell documentation

Page 2 of 9

Kingsbell uses Shopify CLI for development, validation, remote preview, and packaging. Use a dedicated Shopify development store rather than an active production store while building or testing the theme.

Install prerequisites

Kingsbell requires Node.js 20 or newer and Shopify CLI with theme support.

bash

node --version
npm install --global @shopify/cli @shopify/theme
shopify version

Clone the repository and enter the project directory:

bash

git clone https://github.com/rokadhq/kingsbell.git
cd kingsbell

The repository does not require an application dependency installation for normal Liquid development. The package.json scripts wrap Shopify CLI commands.

Connect a development store

Start the remote development server:

bash

npm run dev -- --store your-store.myshopify.com

Shopify CLI will request authentication when needed and create or reuse a development theme. Keep development and staging stores separate from production data whenever possible.

An example environment file is provided as shopify.theme.toml.example. Copy it only when you need named CLI environments, and never commit store passwords, Admin API tokens, customer data, or private application credentials.

Core commands

bash

npm run dev -- --store your-store.myshopify.com
npm run check
npm run package

Command	Purpose
`npm run dev`	Starts Shopify's development preview and synchronizes local changes.
`npm run check`	Runs Theme Check using the repository configuration.
`npm run package`	Creates a Shopify theme ZIP from supported theme directories.

The CI pipeline also runs a deterministic static audit before packaging.

Development workflow

Use a reviewable branch for each change:

bash

git checkout -b theme/example-change
npm run check
npm run dev -- --store your-store.myshopify.com

While previewing:

test the changed section in the theme editor;
save and reload the template;
verify desktop and mobile layouts;
use keyboard-only navigation;
test with and without JavaScript where progressive enhancement is expected;
test empty, loading, error, sold-out, sale, and high-variant states where relevant;
run Theme Check again before committing.

Shopify-supported runtime boundary

Kingsbell storefront code belongs only in:

text

assets/
blocks/
config/
layout/
locales/
sections/
snippets/
templates/

Do not place runtime dependencies in repository documentation, QA folders, prototype directories, or companion specifications. .shopifyignore excludes repository-only material from Shopify CLI push and pull operations.

The .design directory is visual reference material. It is not part of the storefront runtime and should not be imported or linked from Liquid templates.

Editing templates and sections

Kingsbell uses Shopify JSON templates. Prefer merchant-configurable composition over hard-coded page structures.

When adding a section:

include valid section schema JSON;
provide usable defaults and presets when the section is merchant-addable;
use Shopify routes, forms, assets, and image helpers;
keep optional content conditional;
preserve keyboard focus and semantic heading order;
avoid parser-blocking external scripts;
keep JavaScript progressively enhanced and scoped to the component;
respect reduced-motion preferences.

When adding a template:

reference existing section types exactly;
keep section ordering explicit;
provide a stable baseline when optional content is missing;
verify the template can be opened and saved in the theme editor.

Working with assets

Use Shopify-hosted assets and image filters rather than fixed external URLs.

For images:

provide meaningful alt text or an intentional empty alt for decorative media;
use responsive image widths and sizes;
avoid shipping unnecessarily large source files;
validate focal points and cropping across breakpoints.

For JavaScript:

defer non-critical behavior;
avoid global state unless the behavior is genuinely global;
reinitialize correctly after theme-editor section reloads;
remove event listeners when components are disconnected;
preserve a usable non-JavaScript state.

Theme Check and static audit

Theme Check is configured at strict suggestion-level enforcement in the release workflow. The static audit validates additional repository constraints, including:

required Shopify files;
JSON and schema syntax;
template section references;
accessibility hazards such as positive tabindex, autofocus, and zoom restrictions;
unsafe _blank links and insecure HTTP references;
hard-coded core storefront routes;
unsupported Sass or robots patterns;
JavaScript and CSS budgets;
product app-block support.

Treat warnings as implementation work, not as release notes to ignore.

Package the theme

Create an installable archive only after checks pass:

bash

npm run check
npm run package

The Phase 8 release workflow generates Kingsbell-0.8.0.zip. Confirm the package version before distribution and install the ZIP into a clean development store before approving it.

Packaging proves that Shopify CLI can assemble the theme. It does not prove that merchant configuration, browser behavior, performance, accessibility, customer accounts, B2B context, or checkout flows are correct.

Secrets and customer data

Never commit:

Shopify passwords or access tokens;
Admin API, Storefront API, or Customer Account API credentials;
private application secrets;
customer exports or order data;
development-store cookies;
production theme settings containing confidential content.

Use Shopify's credential mechanisms and repository secret storage for CI integrations.