vite-plugin-shopify-import-maps v0.5.4
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
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-mapsUsage
Add ES Module Shims to the
<head>tag in yourtheme.liquidfile.Render the
importmapsnippet file before performing any imports:
<script src="{{ 'es-module-shims.js' | asset_url }}" async></script>
{% liquid
render 'importmap'
render 'vite-tag' with 'theme.js'
render 'vite-tag' with 'customers.js'
%}- Add the
vite-plugin-shopify-import-mapsto yourvite.config.jsfile:
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
themeRoot
- Type:
string - Default:
'./'
Root path to your Shopify theme directory.
snippetFile
- Type:
string - Default:
'importmap.liquid'
Specifies the file name of the snippet that include import map.
bareModules
- Type:
boolean | BareModules - Default:
false
export interface BareModules {
defaultGroup: string
groups: Record<string, string | RegExp | Array<string | RegExp>>
}Configure bare specifier remapping for JavaScript modules.
Example:
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:
<script type="importmap">
{
"imports": {
"general/customers": "{{ 'customers.js' | asset_url }}",
"general/modulepreload-polyfill": "{{ 'modulepreload-polyfill.js' | asset_url }}",
"general/theme": "{{ 'theme.js' | asset_url }}",
"helpers/customer-address": "{{ 'customer-address.js' | asset_url }}",
"helpers/shopify_common": "{{ 'shopify_common.js' | asset_url }}",
"helpers/utils": "{{ 'utils.js' | asset_url }}",
"main/header-drawer": "{{ 'header-drawer.js' | asset_url }}",
"main/localization-form": "{{ 'localization-form.js' | asset_url }}",
"main/product-recommendations": "{{ 'product-recommendations.js' | asset_url }}",
"vendors/lodash": "{{ 'lodash.js' | asset_url }}"
}
}
</script>modulePreload
- Type:
boolean - Default:
false
This option when set to true, generates modulepreload link tags below the import map script tag.
<link rel="modulepreload" href="{{ 'customers.js' | asset_url }}">
<link rel="modulepreload" href="{{ 'theme.js' | asset_url }}">Troubleshooting
If you have any problems or have suggestions, welcome to issues.
Importing asset files (e.g. fonts, images) does not use the version parameter from Shopify CDN
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:
{% #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 %}/* 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