vite-plugin-shopline
v0.0.2
Published
Vite plugin providing integration for Shopline themes
Readme
vite-plugin-shopline
Install
npm i vite-plugin-shopline -D
# yarn
yarn add vite-plugin-shopline -D
# pnpm
pnpm add vite-plugin-shopline -DUsage
Add the vite-plugin-shopline to your vite.config.js file and configure it:
import shopline from 'vite-plugin-shopline'
export default {
plugins: [
/* Plugin options are not required, defaults shown */
shopline({
// Root path to your Shopline theme directory (location of snippets, blocks, etc.)
themeRoot: './',
// Front-end source code directory
sourceCodeDir: 'frontend',
// Front-end entry points directory
entrypointsDir: 'frontend/entrypoints',
// Additional files to use as entry points (accepts an array of file paths or glob patterns)
additionalEntrypoints: [],
// Specifies the file name of the snippet that loads your assets
snippetFile: 'vite-tag.html',
})
]
}vite-plugin-shopline does not require you to specify the entry points for your theme. By default, it treats JavaScript and CSS files (including preprocessed languages such as TypeScript, JSX, TSX, and Sass) within the frontend/entrypoints folder in the root of your project as entry points for Vite.
Your code should like this:
/
└── frontend/
├── bar.ts
└── entrypoints/
├── theme.scss
└── theme.ts // use `import 'vite/modulepreload-polyfill'`Adding scripts and styles to your theme
vite-plugin-shopline generates a vite-tag snippet which includes <script> and <link> tags, and all the logic needed to load your assets.
With your Vite entry points configured, you only need to reference them with the vite-tag snippet that you add to the <head> of your theme's layout or blocks:
{{ snippet 'vite-tag' path='theme.ts' }}
{{ snippet 'vite-tag' path='theme.less' }}During development, the vite-tag will load your assets from the Vite development server and inject the Vite client to enable Hot Module Replacement.
In build mode, the snippet will load your compiled and versioned assets, including any imported CSS, and use the asset_url filter to serve your assets from the Shopline content delivery network (CDN).
Polyfill for Shopline 2.0 Themes
For Shopline 2.0 themes that require polyfills:
{{#if themeTypeVersion ">=" 2.1}}
<!-- 2.1 assets -->
{{ snippet 'vite-tag' path='discount.ts' }}
{{ snippet 'vite-tag' path='discount.less' }}
{{else}}
<!-- 2.0 assets -->
{{ snippet 'polyfill-vite-tag' path='discount.ts' }}
{{ snippet 'polyfill-vite-tag' path='discount.less' }}
{{/if}}Legacy Browser Support
Use @vitejs/plugin-legacy and build.target to support older browsers:
import legacy from '@vitejs/plugin-legacy' // version ^5.x
import { defineConfig } from 'vite'
import shopline from 'vite-plugin-shopline'
export default defineConfig({
build: {
// Transform esnext to es2015, like: [??] to [a != null ? a : b]
target: ['es2015', 'chrome58'],
},
plugins: [
// Add polyfills for ES features, like: [ Set, Promise.allSettled, etc. ]
legacy({
modernPolyfills: true,
modernTargets: ['chrome>=70'],
polyfills: false,
renderLegacyChunks: false,
}),
shopline(),
],
})Loading additionalEntrypoints
{{ snippet 'vite-tag' path='~/bar.ts' }}
{{ snippet 'vite-tag' path='@/foo.ts' }}{{ snippet 'vite-tag' path='/resource/demo.ts' }}Preloading stylesheets
You can pass the preload_stylesheet parameter to the vite-tag snippet to enable the preload parameter of the stylesheet_tag filter. Use it sparingly. For example, consider preloading only render-blocking stylesheets.
{{ snippet 'vite-tag' path='theme.less' preload_stylesheet=true }}Import aliases
For convenience, ~/ and @/ are aliased to your frontend folder, which simplifies imports:
import App from '@/components/a.ts'
import '@/styles/a.css'Example
Directory Structure
.
├── assets
│ ├── bar-Blak-Iq_.js
│ ├── demo-C3QzQUB2.js
│ ├── foo-BkD6IY0z.js
│ ├── theme-eQ3z514Y.js
│ └── theme-lfT4LnnD.css
├── blocks
│ ├── .gitkeep
│ └── app-embed-block.html
├── frontend
│ ├── entrypoints
│ │ ├── theme.less
│ │ └── theme.ts
│ ├── bar.ts
│ └── foo.ts
├── locales
│ └── .gitkeep
├── resources
│ └── demo.js
└── snippets
├── .gitkeep
└── vite-tag.htmlvite.config.ts
import shopline from 'vite-plugin-shopline'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
shopline({
// Additional files to use as entry points (accepts an array of file paths or glob patterns)
additionalEntrypoints: ['frontend/bar.ts', 'frontend/foo.ts', 'resources/*.js'],
// Front-end entry points directory
entrypointsDir: 'frontend/entrypoints',
// Specifies the file name of the snippet that loads your assets
snippetFile: 'vite-tag.html',
// Front-end source code directory
sourceCodeDir: 'frontend',
// Root path to your Shopline theme directory (location of snippets, blocks, etc.)
themeRoot: './',
}),
],
})blocks/app-embed-block.html
{{ snippet 'vite-tag' path='theme.ts' }}
{{ snippet 'vite-tag' path='theme.less' preload_stylesheet=true }}
{{ snippet 'vite-tag' path='~/bar.ts' }}
{{ snippet 'vite-tag' path='@/foo.ts' }}
{{ snippet 'vite-tag' path='/resources/demo.js' }}Advanced Features
Keep Assets
Keep /assets/* files using the clean plugin, which uses /assets/.vite/manifest.json to remove outdated files:
import shopline, { clean } from 'vite-plugin-shopline'
export default defineConfig({
build: {
emptyOutDir: false,
},
plugins: [
clean(),
shopline()
],
})Alternatively, use public dir to copy static files:
export default defineConfig({
publicDir: './public',
plugins: [shopline()],
})Remove File Hash
export default defineConfig({
build: {
rollupOptions: {
output: {
entryFileNames: '[name].js',
chunkFileNames: '[name].js',
assetFileNames: '[name][extname]',
},
},
},
})Examples
See the vite-shopify-example example for a complete demonstration of vite-plugin-shopline usage.
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: