vite-plugin-shopify-easel 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Easel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# Easel
+
+Easel is a Vite plugin for Shopify Liquid themes.
+
+It builds JavaScript, TypeScript, and CSS into Shopify theme assets, generates the Liquid snippet that loads them, and safely replaces old build output. During development, it can coordinate Vite updates with Shopify CLI reloads. Shopify CLI still handles previews, syncing, and deployment.
+
+[Read the documentation](https://easel.billynoyes.co.uk/docs/)
+
+## Install
+
+```sh
+pnpm add -D vite-plugin-shopify-easel vite
+```
+
+Easel requires Node.js 22.12 or newer and supports Vite 7 and 8.
+
+## Start
+
+Keep the Shopify theme at the project root and place source files in `src`.
+
+```text
+assets/
+config/
+layout/
+sections/
+snippets/
+templates/
+src/
+  main.ts
+  style.css
+vite.config.ts
+```
+
+`src/main.js` also works.
+
+```ts
+import {defineConfig} from 'vite';
+import easel from 'vite-plugin-shopify-easel';
+
+export default defineConfig({
+  plugins: [easel()],
+});
+```
+
+Render the generated loader in `layout/theme.liquid`.
+
+```liquid
+{% render 'easel-assets' %}
+```
+
+Ignore generated output.
+
+```gitignore
+.easel/
+assets/easel-*
+snippets/easel-assets.liquid
+```
+
+Run Vite and Shopify CLI in separate terminals.
+
+```sh
+npm run dev
+```
+
+```sh
+shopify theme dev --notify .easel/shopify-ready
+```
+
+The notification is optional. Vite HMR and Shopify CLI live reload still work without it.
+
+Build before pushing or packaging.
+
+```sh
+npm run build
+shopify theme push
+```
+
+## Named bundles
+
+Load only the code each Liquid surface needs.
+
+```ts
+import {defineConfig} from 'vite';
+import easel from 'vite-plugin-shopify-easel';
+
+export default defineConfig({
+  plugins: [
+    easel({
+      bundles: {
+        theme: {script: 'main.ts', style: 'style.css'},
+        product: {script: 'product.ts', style: 'product.css'},
+        typography: {style: 'typography.css'},
+      },
+    }),
+  ],
+});
+```
+
+```liquid
+{% render 'easel-assets', entry: 'product' %}
+```
+
+Bundle paths resolve from `src` by default. The first bundle is used when `entry` is omitted.
+
+## Configuration
+
+```ts
+easel({
+  // Shopify theme directory relative to the Vite root. Defaults to the Vite root.
+  theme: '.',
+
+  // Source directory relative to the Vite root. Defaults to src.
+  source: 'src',
+
+  // Named entries relative to source. Defaults to main.ts or main.js with style.css.
+  bundles: {
+    theme: {script: 'main.ts', style: 'style.css'},
+  },
+
+  // Namespace used by generated assets and the Liquid snippet. Defaults to easel.
+  namespace: 'easel',
+
+  // Shopify CLI reload coordination. Use false to disable it.
+  refresh: {
+    // Notification file relative to the Vite root.
+    signal: '.easel/shopify-ready',
+
+    // Reload debounce in milliseconds. Defaults to 100.
+    delay: 100,
+  },
+});
+```
+
+Use Tailwind CSS, Alpine.js, React, Vue, Sass, PostCSS, and other tools through their normal Vite setup. React Fast Refresh requires `@vitejs/plugin-react/preamble` because Easel does not use an HTML entry.
+
+## Safe by default
+
+Easel never empties Shopify's shared `assets` directory. It tracks only its own files, refuses unsafe overwrites, stages builds in isolation, serializes publication, and rolls back interrupted commits.
+
+Production entries keep stable names. Shared chunks, dynamic chunks, imported CSS, images, fonts, and source maps retain Vite's cache safe output behavior.
+
+Shopify CLI remains responsible for authentication, previews, synchronization, pushes, and packaging.
+
+## Examples
+
+• [`examples/vanilla`](examples/vanilla) for TypeScript and CSS
+
+• [`examples/alpine-tailwind`](examples/alpine-tailwind) for Alpine.js and Tailwind CSS
+
+• [`examples/react`](examples/react) for React inside Liquid sections
+
+• [`examples/vue`](examples/vue) for Vue single file components inside Liquid sections
+
+Each example includes Shopify Theme Editor lifecycle handling, passes CI, and has been tested against a real Shopify development store.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { Plugin } from 'vite';
+
+interface EaselBundle {
+    script?: string;
+    style?: string;
+}
+interface EaselRefreshOptions {
+    /** Shopify CLI --notify file relative to Vite's root. */
+    signal?: string;
+    /** Delay used to combine repeated Shopify CLI notifications. */
+    delay?: number;
+}
+interface EaselOptions {
+    /** Shopify theme path relative to Vite's root. Defaults to the Vite root. */
+    theme?: string;
+    /** Source path relative to Vite's root. Defaults to "src". */
+    source?: string;
+    /** Named storefront bundles. Defaults to src/main.ts or src/main.js plus src/style.css. */
+    bundles?: Record<string, EaselBundle>;
+    /** Namespace used for generated assets and the Liquid loader. Defaults to "easel". */
+    namespace?: string;
+    /** Shopify-aware full-page refresh. Enabled by default. */
+    refresh?: boolean | EaselRefreshOptions;
+}
+
+declare function easel(options?: EaselOptions): Plugin[];
+
+export { type EaselBundle, type EaselOptions, type EaselRefreshOptions, easel as default, easel };