🗄️File Structure

Review Platter Base's file structure before getting started.

File Structure

`./@types`

TypeScript types for Shopify theme settings, sections, and section inputs. These are mostly auto-generated according to the global type declaration in ./@types/types.d.ts. This applies to anything that binds to the window object and to small help types.

`./assets`

These are a local version of the theme's ./asset folder, which that are one-way synced into the working theme as set by the env variable: SHOPIFY_THEME_FOLDER .

This method of syncing ensures that individual store's themes can have their own assets, and that only files that are part of Platter Base are upgraded when running the dev tools. The files in the ./asset folder are split into 3 categories:

Integrated Developer Tools

These are all the config files that get loaded into the theme, to allow merchants run the integrated dev tools on their own machines.

TypeScript & TailwindCSS

These files are the source files for specific section / global functionality throughout the theme. If a file relates back to only a specific section / block, the file convention is {section_name}.{block_name}.tsx.

If a TS file is responsible to render entire components, it is important to check if server side rendering via a related .liquid file is necessary.

Static server side rendering should generally be implemented first, with identical classes to ensure that there is no Cumulative Layout Shift on page load.

Compiled & Auto Generated

These files include the theme.js, _types.d.ts, and tailwind.css.liquid, which are auto generated by the 3 different dev tools: esbuild, shopify-theme-dev, and tailwindcss

`./globals`

`./globals/settings_schema.ts`

These are the global theme settings that are editable in the Theme Editor. These settings are transpiled via the shopify-theme-dev package.

`./globals/settings`

These are helper files to load theme and section settings into many different areas at once, making it possible to easily repeat settings in different places.

These files get only accessed by the settings_schema.ts and any ./sections/{section_name}/schema.ts

`./globals/layouts`

The theme.liquid file is the root entry point for Shopify files.

It is extremely common for Apps and Merchants to make changes to their own /layouts/theme.liquid file, and generally this file gets excluded from upgrades and should be manually upgraded.

The env variable SHOPIFY_CMS_IGNORE_LAYOUTS=theme.liquid blocks automatic updates. Removing the env variable will enable overriding the theme.liquid

`./globals/snippets`

Snippets are helper files to render repeated layouts. There are generally 2 types of files in the folder that have different meanings by their filename. Files starting with _ are global helper utils that are not responsible to generate any visual layout. They are small helpers to properly load images or icons and any specific data models. The other files are global layouts that are accessible within any area of the theme via {% render %} tags. Block scoped snippets should be in their related sections folder and not here.

`./sections`

These are all the Shopify sections in the theme, organized on a per folder per section basis. Each folder name should be in kebab-case as it provides the name for the section.

Naming of sections and the content of the schema.ts need to be 100% accurate to work with the dev tools.

Section names should be semantic with regards to what they do, as well as in relation to the Figma theme naming convention.

Once a name has been set and used in multiple stores, it is not possible to change the name as it would break backwards compatibility.

`./schema.ts`

This is the starting point for any section, and it contains all settings that will be available within the settings in the Theme Editor.

For a section named side-by-side-image, for example, the entry file would be ./sections/side-by-side-image/schema.ts

import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by Side Image", // This is what Shows in the Theme Editor on the Left, if the section has no setting with the id `title`
  settings: [],
	blocks: [],
  presets: [
    {
      name: "Side by Side Image", // This shows in the Theme editor when Searching for the Section when adding a new one.
    },
  ],
};

If any of the bold and underlined names are not exact as per the naming conventions based on the filename, the dev tools will not work.

Once the new section is created, you can add settings and blocks and any other valid property as per the Shopify section input types and section architecture.

The shopify-theme-dev script will auto generate the side-by-side-image.liquid file and any block file as side-by-side-image.{block_type}.liquid .

Any changes on the settings for the Section or Blocks, will auto generate the variables on the top of either file.

You can also opt out of auto generating the block-level files by adding the top level property generate_block_files: ["block_type_to_autogenerate"] or generate_block_files: []

import { ShopifySection } from "types/shopify";
import { SideBySideImageSection } from "types/sections";

export const sideBySideImage: ShopifySection<SideBySideImageSection> = {
  name: "Side by side image",
  generate_block_files: ["image"], // Only the `image` Block will be generated as `side-by-side-image.image.liquid, Set to [] and no block files will be created  
  settings: [],
  blocks: [
    {
      type: "image",
      name: "Image",
      settings: [],
    },
    {
      type: "text",
      name: "Text",
      settings: [],
    },
  ],
  presets: [
    {
      name: "Side by side image",
    },
  ],
};

`./{section_name}.liquid`

This is the root Liquid file for any section, which get compiled together with the ./schema.ts based on the env vairables SHOPIFY_THEME_FOLDER/sections, by the shopify-theme-dev package.

The variables and types from the schema will be auto generated on top of the file.

{%- comment -%} Auto Generated Variables start {%- endcomment -%}
{%- liquid
  ...
  assign title = section.settings.title
  ...
-%}
{%- comment -%} Auto Generated Variables end {%- endcomment -%}

`./{section_name}.{block_type}.liquid`

These are files each section block and get copied over into the SHOPIFY_THEME_FOLDER/snippets folder.

Any *.liquid file also accepts auto translations that are generated for JS and Shopify’s locales/en.default.json by placing text content in a special tag.

For example, "Add to Cart" becomes {{ "product_card.add_to" | t }} and window.translations.product_card.add_to = "Add to Cart"; via the translations.liquid snippet.