Working on the tailwind theme

Setup

New projects

Once the tailwind project has been installed on your local PC, you can begin developing on the theme.

For existing projects

You will be able to directly run the workflow with npm run dev. The directory will already be setup and the structure can be followed.

1. Project structure

Each project is arranged with both source and distribution copies of all theme files.

Distribution files in ./

The distribution files of the project are contained in the root folder of your project. These are the files that Shopify CLI uploads to Shopify as the theme for the store you are signed into. Important: These files should not be edited directly. Any changes you make here will be overwritten by the development tools.

Source files in ./_src/

The source files are contained in the _src/ folder of your project. These are the files that you are free to edit. The project development tools will watch all files in this folder for changes and generate new distribution copies as required ready for uploading to Shopify.

For a detailed list and explanation of sections and features included in the StudioForty9 Tailwind theme please read the Theme developer section

2. Tailwind and CSS

All custom CSS should be contained in the ./_src/styles/ folder.

Tailwind CSS is used to speed up CSS development. Tailwind is compiled into vanilla CSS. This means developers are not tied to using only Tailwind CSS classes. In fact, the theme is moving away from the in-line utility-class approach and towards a BEM approach to CSS class naming while @apply-ing Tailwind classes in CSS stylesheet files. This separation of CSS and HTML makes for easier to read and maintain code and facilitates the re-use of components.

Tailwind UI has been used to facilitate the rapid development of UI components in the theme. When creating new components, sections or even full page layouts it is encouraged developers first check if a similar design is available in the Tailwind UI library. Only if no suitable starting point is available should components be built from scratch. However, Tailwind UI components are used as a starting point and the theme is not constrained by or limited to the components available in the Tailwind UI library.

Theme stylesheet

./_src/styles/theme.css is the main theme stylesheet. A distribution copy will be generated from this file and placed in ./assets/theme.css which is included in the head of ./layout/theme.liquid

Organising CSS

Where possible, each page, section, and re-usable component should have its own CSS file. This file should be named to match the component and placed in the most appropriate subfolder. E.g. the stylesheet associated with the header section (./_src/sections/header.liquid) can be found in _src/styles/sections/header.css

If adding new stylesheets in any of the styles subfolders please ensure you add an @import rule to the folder’s index.css file. Failure to do so will mean the new file will not be processed by Tailwind and will not be included in the theme stylesheet. For example, ./_src/styles/sections/index.css contains the following rule @import './header'; to include the header’s styles in the theme.css file.

Liquid in CSS

We do not want to include any Liquid code in our CSS files. CSS rules that are dependent on Theme settings or on Liquid logic should use one of the following alternatives.

Use Liquid conditions to add Tailwind CSS classes

E.g. <div class=" max-w-site">

Use CSS custom properties

CSS custom properties can be defined in ./_src/snippets/theme-settings.liquid which allows the use of Liquid code or theme settings. This is useful for defining theme fonts as selected in the Theme Customiser for example.

3. Javascript

Javascript files should be placed in the ./_src/scripts/ folder.

Where possible Javascript should be specific to a section or page and should only be included on the required page or if the associated section is used on the current page.

4. Icons

Icons should be in SVG format and placed in the ./_src/icons folder.

The development tools will process all icons in this folder, optimising them and concatenating them into a single Liquid file in ./snippets/icon.liquid

Icons can then be referenced in any Liquid code using

More information on the icon.liquid component can be found here. TODO: link to icon WIKI page

5. Page templates

In Online Store 2.0 themes page templates should contain only JSON information listing the sections to include on pages using that template. This information is updated based on changes made in the theme customiser in Shopify.

To avoid overwriting changes made online, only a single copy of these JSON templates is kept in the ./templates/ folder. There are no corresponding copies in the source folder.

6. Theme settings

In Online Store 2.0 themes theme settings are spread across a number of files.

Global theme settings (as defined in ./config/settings_schema.json) are stored in ./config/settings_data.json. Page settings and sections used are stored in each individual page template’s JSON file in the ./templates/ folder.

NOTE The Shopify theme server creates a temporary theme copy online. This theme copy only exists while the Shopify theme server is active (which is started by running npm run dev). Once the Shopify theme server instance is terminated any customiser changes are lost.

To avoid losing theme setting changes, a copy of the theme needs to be downloaded while the theme server is still active. This can be done by running shopify theme pull --theme THEME_ID ./_backup where THEME_ID is the ID generated by Shopify CLI and displayed along with the preview links.

This command will download a copy of the uploaded theme along with all settings into the ./_backup/ folder. Copying the ./_backup/config/settings_data.json and ./_backup/templates/*.json files into your project’s root will preserve any customiser changes.