theme-graph

Theme Graph

A data structure that represents your Shopify theme

A Shopify Theme Graph is a data structure that spans Liquid, JSON, JavaScript and CSS files.

It has the following interface:

interface ThemeGraph {
  rootUri: UriString; // e.g. 'file:/path/to/horizon'
  entryPoints: ThemeModule[];
  modules: Record<UriString, ThemeModule>
}

A ThemeModule holds dependencies and references of a module. For instance,

interface LiquidModule {
  uri: UriString;
  type: 'liquid';
  kind: 'block' | 'layout' | 'section' | 'snippet' | 'template';
  references: Reference[];
  dependencies: Reference[];
}

For a module $M$,

• a reference is a backlink to other modules that depend on $M$,
• a dependency is a dependent link on another module.

interface Reference {
  /* The file that initiated the dependency/reference */
  source: { uri: string, range?: Range };

  /* The file that it points to */
  target: { uri: string, range?: Range };

  type:
    | 'direct'   // e.g. {% render 'child' %}, {{ 'theme.js' | asset_url }}, <custom-element>, etc.
    | 'indirect' // e.g. Sections and blocks that accept theme blocks
    | 'preset'   // e.g. Section and block presets
}

See types.md for more details and how-it-works.md for an overview of the algorithm.

Installation

npm install @shopify/theme-graph

Usage

Through the VS Code extension

The theme graph is used by the VS Code extension to power the dependencies, references and dead code features.

From the CLI

Usage:
  theme-graph <path-to-theme-directory>

Example:
  theme-graph horizon > graph.json

As a library

See bin/theme-graph for inspiration.

Contributing

See CONTRIBUTING.md.