Astra-plugin NPM

Astra

astra-plugin aims to integrate Vite as seamlessly as possible with Shopify themes for a best-in-class developer experience.

Features

⚡️ Everything Vite provides, plus:
🤖 Automatic entrypoint detection
🏷 Smart generation of script and link tags for entrypoints
🌎 Full support for assets served from Shopify CDN
👌 Zero-Config

Install

npm i astra-plugin -D

# yarn
yarn add astra-plugin -D

# pnpm
pnpm add astra-plugin -D

Usage

Vite Plugin

Add the astra-plugin plugin to vite.config.js / vite.config.ts:

import astra from "astra-plugin";

export default {
  plugins: [
    /* Plugin options are not required, defaults shown */
    astra({
      // Root path to your Shopify theme directory (location of snippets, sections, templates, etc.)
      themeRoot: "./",
      // Front-end source code directory
      sourceCodeDir: "src",
      // Front-end entry points directory
      entrypointsDir: "src/entry",
      // Additional files to use as entry points (accepts an array of file paths or glob patterns)
      additionalEntrypoints: [],
    }),
  ],
};

You can customize this file as needed. Check Vite's plugins and config reference for more info.

File structure

The Shopify Vite plugin treats each script and stylesheet in the entrypoints directory (src/entrypoints by default) as an input for the Vite build. You can organize the rest of your frontend code however you'd like. For example:

src
  ├── index.ts # entry point for JS files
  ├── theme.css # entry point for CSS and style files
  │   
  │ # Additional frontend source files to be imported from entrypoints
  │── components
  │   └── App.vue
  │── stylesheets
  │   └── my_styles.css
  └── images
      └── logo.svg

Only script and stylesheet files are supported as entrypoints.
You can customize where astra loads entrypoints by specifying a value for the entrypointsDir plugin option.

Adding scripts and styles to your theme

In your <head> element add this

Then render the astra snippet (in your <head> element too) to insert tags for loading assets from a given entrypoint file:

{% render 'astra' with 'theme.ts' %}

astra will generate new versions of astra.liquid during development and on each production build.
The astra snippet will render HTML tags to load the provided entrypoint.
Script tags are generated with a type="module" and crossorigin attributes like Vite does by default.
In production mode, the asset_url filter is used to load resources from the Shopify CDN.
In production mode, the astra snippet will automatically render separate tags for loading stylesheets and preloading imported JS chunks.
When running the development server, these tags are omitted, as Vite will load the dependencies as separate modules.
During development, the astra snippet will render a <script> that includes the Vite client script to enable HMR.

{% render 'astra' with 'theme.ts' %}

# HTML output (development)
<script src="http://localhost:5173/theme.ts" type="module"></script>

# HTML output (production)
<link rel="stylesheet" href="{{ 'theme.4d95c99b.css' | asset_url }}">
<script src="{{ 'theme.3b623fca.js' | asset_url }}" type="module" crossorigin="anonymous"></script>
<link href="{{ 'lodash.13b0d649.js' | asset_url }}" rel="modulepreload" as="script" crossorigin="anonymous">

In development mode, assets are loaded from the Vite development server host.
In production mode, assets are loaded from the Shopify CDN using the asset_url filter and a relative base path.

Loading additionalEntrypoints:

# Relative to sourceCodeDir
{% render 'astra' with '@/foo.ts' %}
{% render 'astra' with '~/foo.ts' %}

# Relative to themeRoot
{% render 'astra' with '/resources/bar.ts' %} # leading slash is required

Preloading stylesheets:

{% render 'astra' with 'theme.css', preload: true %}

Note: The preload parameter will enable the preload parameter of the stylesheet_tag, use it sparingly e.g. consider preloading only render-blocking stylesheets. Learn more

Import aliases

For convenience, ~/ and @/ are aliased to your src folder, which simplifies imports:

import App from "@/components/App.vue";
import "@/styles/my_styles.css";

Bugs

Please create an issue if you found any bugs, to help us improve this project!

Thanks

We would like to specifically thank the following projects, for inspiring us and helping guide the implementation for this plugin by example:

astra shopify shopify themes shopify theme dev vite plugin

debug fast-glob astra-cli-kit

0.1.1

3 years ago

0.1.0

3 years ago