vite-plugin-shopify-import-maps

The vite-plugin-shopify-import-maps enhances Shopify theme development by adding support for import-maps which can be used to control the resolution of module specifiers.

Requirements

Before using this plugin, make sure you have the vite-plugin-shopify installed. This plugin provides the necessary underlying setup for developing Shopify themes with Vite.

Install

``bash
npm i -D vite-plugin-shopify-import-maps

yarn

yarn add -D vite-plugin-shopify-import-maps

pnpm

pnpm add -D vite-plugin-shopify-import-maps
`

Usage

1. Add ES Module Shims to the tag in your theme.liquid file.

2. Render the importmap snippet file before performing any imports:

`liquid


{% liquid
render 'importmap'
render 'vite-tag' with 'theme.js'
render 'vite-tag' with 'customers.js'
%}
`

3. Add the vite-plugin-shopify-import-maps to your vite.config.js file:

`js
import { defineConfig } from 'vite'
import shopify from 'vite-plugin-shopify'
import importMaps from 'vite-plugin-shopify-import-maps'

// Recommended configuration
export default defineConfig({
build: {
rollupOptions: {
output: {
entryFileNames: '[name].js',
chunkFileNames: '[name].js',
assetFileNames: '[name].[ext]'
}
}
},
plugins: [
shopify({ versionNumbers: true }),
importMaps({ bareModules: true })
]
})
`

After executing the build command, the importmap.liquid file will be generated in the snippets folder in your theme root directory.

Options

$3

- Type: string
- Default: './'

Root path to your Shopify theme directory.

$3

- Type: string
- Default: 'importmap.liquid'

Specifies the file name of the snippet that include import map.

$3

- Type: boolean | BareModules
- Default: false

`ts
export interface BareModules {
defaultGroup: string
groups: Record>
}
`

Configure bare specifier remapping for JavaScript modules.

Example:

`ts
export default defineConfig({
plugins: [
importMap({
bareModules: {
defaultGroup: 'main', // By default is 'main'
groups: {
helpers: /frontend\/lib/, // RegExp pattern
vendors: 'node_modules', // String
general: ['frontend/entrypoints', /vite/] // Array of string or RegExp pattern
}
}
})
]
})
`

This generates the importmap.liquid file:

`liquid

`

$3

- Type: boolean
- Default: false

This option when set to true, generates modulepreload link tags below the import map script tag.

`liquid


`

Troubleshooting

If you have any problems or have suggestions, welcome to issues.

$3

This is not the scope of import map, as it is are designed to manage javascript modules. But you can load assets from Liquid files using the asset_url filter and consume them via CSS variables:

`liquid
{% #theme.liquid %}

{% style %}
@font-face {
font-family: 'Anton';
src: url("{{ 'anton-v23-latin-regular.woff2' | asset_url }}") format('woff2');
font-display: swap;
}

:root {
--font-heading-family: 'Anton', sans-serif;
--background-image: url('{{ 'background-image.svg' | asset_url }}');
}
{% endstyle %}
`

`css
/ styles.css /

h1,
h2,
h3 {
font-family: var(--font-heading-family);
}

body {
background-image: var(--background-image);
}
``

Acknowledges

- vite-plugin-shopify - Shopify theme development using Vite