nuxt-shopify-embedded 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qvdp
+
+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,258 @@
+# nuxt-shopify-embedded
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Nuxt module for building Shopify embedded apps with ease.
+
+- [✨ Release Notes](/CHANGELOG.md)
+- [📖 Documentation](#features)
+
+## Features
+
+- 🔐 **Shopify API Client** — Pre-configured `@shopify/shopify-api` instance with automatic settings
+- 📊 **GraphQL Client** — Type-safe GraphQL queries with session management
+- 🎨 **Polaris Components** — Use Shopify Polaris web components (`<s-*>` tags) out of the box
+- 🌉 **App Bridge CDN** — Automatic injection of App Bridge and Polaris scripts
+- 📦 **Type-Safe Config** — Full TypeScript support with runtime configuration
+- 🔧 **Auto-Imports** — Server composables auto-imported, ready to use
+
+## Quick Setup
+
+### 1. Install the module
+
+```bash
+# Using pnpm
+pnpm add nuxt-shopify-embedded
+
+# Using npm
+npm install nuxt-shopify-embedded
+
+# Using yarn
+yarn add nuxt-shopify-embedded
+```
+
+### 2. Add to your Nuxt config
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-shopify-embedded'],
+
+  shopifyEmbedded: {
+    apiKey: process.env.SHOPIFY_API_KEY,
+    apiSecret: process.env.SHOPIFY_API_SECRET,
+    appUrl: process.env.SHOPIFY_APP_URL,
+    scopes: process.env.SHOPIFY_APP_SCOPES,
+  },
+})
+```
+
+### 3. Set up environment variables
+
+```bash
+# .env
+SHOPIFY_API_KEY=your-api-key
+SHOPIFY_API_SECRET=your-api-secret
+SHOPIFY_APP_URL=https://your-app.com
+SHOPIFY_APP_SCOPES=read_products,write_products
+```
+
+That's it! You can now use Shopify utilities in your app ✨
+
+## Usage
+
+### Server Composables
+
+#### `useShopifyAPI()`
+
+Returns the singleton Shopify API instance. Used for session token decoding, token exchange, and other API operations.
+
+```typescript
+const shopify = useShopifyAPI()
+
+// Decode a session token
+const decoded = await shopify.session.decodeSessionToken(token)
+
+// Exchange for offline access token
+const response = await shopify.auth.tokenExchange({ shop, sessionToken, requestedTokenType })
+```
+
+#### `useShopifyGraphQL(shop, accessToken)`
+
+Creates a GraphQL client for a specific shop. Returns a Shopify `GraphqlClient` instance.
+
+```typescript
+// server/api/products.get.ts
+export default defineEventHandler(async (event) => {
+  const { shop, accessToken } = event.context.session
+
+  const graphql = useShopifyGraphQL(shop.domain, accessToken)
+
+  const result = await graphql.request(`
+    query GetProducts($first: Int!) {
+      products(first: $first) {
+        edges {
+          node { id, title }
+        }
+      }
+    }
+  `, { variables: { first: 10 } })
+
+  return result.data
+})
+```
+
+### Polaris Components
+
+Use Shopify Polaris components directly in your Vue templates with the `s-` prefix:
+
+```vue
+<template>
+  <s-page title="Dashboard">
+    <s-layout>
+      <s-layout-section>
+        <s-card>
+          <s-text as="h2" variant="headingMd">Welcome to your app</s-text>
+          <s-button @click="handleClick">Click me</s-button>
+        </s-card>
+      </s-layout-section>
+    </s-layout>
+  </s-page>
+</template>
+```
+
+### App Bridge
+
+App Bridge is automatically loaded. Access it via `window.shopify`:
+
+```typescript
+// In your Vue component
+const toast = window.shopify.toast.show('Product saved!')
+
+// Navigate using App Bridge
+window.shopify.navigate('/products')
+```
+
+### Runtime Config
+
+Access Shopify configuration in your app:
+
+```typescript
+// Client-side (public values only)
+const config = useRuntimeConfig()
+console.log(config.public.shopifyEmbedded.apiKey)
+console.log(config.public.shopifyEmbedded.appUrl)
+
+// Server-side (all values including secrets)
+const config = useRuntimeConfig()
+console.log(config.shopifyEmbedded.apiSecret)
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | ✅ | Your Shopify app's API key |
+| `apiSecret` | `string` | ✅ | Your Shopify app's API secret |
+| `appUrl` | `string` | ✅ | Your app's public URL |
+| `scopes` | `string` | ✅ | Comma-separated OAuth scopes |
+
+## TypeScript
+
+This module provides full TypeScript support including:
+
+- Module options autocomplete
+- Runtime config types
+- Global `Window` types for `window.shopify` (App Bridge) and `window.Polaris`
+- GraphQL client response types
+
+## Comparison with Alternatives
+
+| Feature | nuxt-shopify-embedded | Shopifast (React) |
+|---------|----------------------|-------------------|
+| Framework | Nuxt / Vue 3 | Remix / React |
+| Server Runtime | Nitro | Remix |
+| Component Library | Polaris Web Components | Polaris React |
+| Deployment | Any (Vercel, Cloudflare, etc.) | Vercel |
+| Open Source | ✅ MIT License | Paid |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Prepare the module
+pnpm dev:prepare
+
+# Start the playground
+pnpm dev
+
+# Start with Shopify CLI (for OAuth testing)
+pnpm dev:shopify
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm lint
+
+# Type check
+pnpm test:types
+```
+
+### Running the playground with Shopify CLI
+
+The playground is a working Shopify embedded app. To run it against a real Shopify store, you need the [Shopify CLI](https://shopify.dev/docs/api/shopify-cli#installation) installed globally:
+
+```bash
+npm install -g @shopify/cli @shopify/theme
+```
+
+Then link your Shopify app configuration to the project:
+
+```bash
+shopify app config link
+```
+
+This creates the required `.toml` configuration files at the root of the project. Once linked, start the playground with:
+
+```bash
+pnpm dev:shopify
+```
+
+This runs `shopify app dev` inside the playground directory, which handles the OAuth tunnel and embeds your app in the Shopify admin.
+
+## Contributing
+
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting a PR.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+[MIT License](LICENSE)
+
+---
+
+Made with ❤️ for the Nuxt & Shopify community
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-shopify-embedded/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-shopify-embedded
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-shopify-embedded.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-shopify-embedded
+
+[license-src]: https://img.shields.io/npm/l/nuxt-shopify-embedded.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-shopify-embedded
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    apiKey: string;
+    apiSecret: string;
+    appUrl: string;
+    scopes: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-shopify-embedded",
+  "configKey": "shopifyEmbedded",
+  "compatibility": {
+    "nuxt": "^4.0.0"
+  },
+  "version": "0.1.4",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,74 @@
+import { defineNuxtModule, createResolver, addServerImportsDir, addTypeTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-shopify-embedded",
+    configKey: "shopifyEmbedded",
+    compatibility: { nuxt: "^4.0.0" }
+  },
+  defaults: {
+    apiKey: "",
+    apiSecret: "",
+    appUrl: "",
+    scopes: ""
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const requiredFields = ["apiKey", "apiSecret", "appUrl", "scopes"];
+    const missingFields = requiredFields.filter((field) => !options[field]);
+    if (missingFields.length > 0) {
+      console.warn(
+        `[nuxt-shopify-embedded] Missing configuration: ${missingFields.join(", ")}. Some features may not work correctly.`
+      );
+    }
+    nuxt.options.runtimeConfig = defu(nuxt.options.runtimeConfig, {
+      shopifyEmbedded: {
+        apiKey: options.apiKey,
+        apiSecret: options.apiSecret,
+        appUrl: options.appUrl,
+        scopes: options.scopes
+      },
+      public: {
+        shopifyEmbedded: {
+          apiKey: options.apiKey,
+          appUrl: options.appUrl
+        }
+      }
+    });
+    const existingCheck = nuxt.options.vue.compilerOptions?.isCustomElement;
+    nuxt.options.vue.compilerOptions ||= {};
+    nuxt.options.vue.compilerOptions.isCustomElement = (tag) => {
+      if (tag.startsWith("s-")) return true;
+      return existingCheck?.(tag) ?? false;
+    };
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addTypeTemplate({
+      filename: "types/nuxt-shopify-embedded.d.ts",
+      getContents: () => `
+import type { ShopifyGlobal } from '@shopify/app-bridge-types'
+import type { PolarisGlobal } from '@shopify/polaris-types'
+
+declare global {
+  interface Window {
+    shopify: ShopifyGlobal
+    Polaris: PolarisGlobal
+  }
+}
+
+export {}
+`
+    });
+    nuxt.options.app.head.script = nuxt.options.app.head.script || [];
+    nuxt.options.app.head.script.push(
+      {
+        "src": "https://cdn.shopify.com/shopifycloud/app-bridge.js",
+        "data-api-key": options.apiKey,
+        "tagPosition": "head"
+      },
+      { src: "https://cdn.shopify.com/shopifycloud/polaris.js" }
+    );
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/server/utils/useShopifyAPI.d.ts

@@ -0,0 +1,4 @@
+import { shopifyApi } from '@shopify/shopify-api';
+type ShopifyApiInstance = ReturnType<typeof shopifyApi>;
+export declare function useShopifyAPI(): ShopifyApiInstance;
+export {};

package/dist/runtime/server/utils/useShopifyAPI.js

@@ -0,0 +1,43 @@
+import { nodeAdapterInitialized } from "@shopify/shopify-api/adapters/node";
+import { shopifyApi, ApiVersion } from "@shopify/shopify-api";
+import { useRuntimeConfig } from "#imports";
+if (!nodeAdapterInitialized) {
+  throw new Error("Node adapter not initialized");
+}
+let shopifyApiInstance = null;
+export function useShopifyAPI() {
+  if (shopifyApiInstance) {
+    return shopifyApiInstance;
+  }
+  const config = useRuntimeConfig();
+  const apiKey = config.shopifyEmbedded.apiKey;
+  const apiSecret = config.shopifyEmbedded.apiSecret;
+  const appUrl = config.shopifyEmbedded.appUrl;
+  const scopes = config.shopifyEmbedded.scopes;
+  if (!appUrl) {
+    throw new Error("SHOPIFY_APP_URL is not defined");
+  }
+  if (!apiSecret) {
+    throw new Error("SHOPIFY_API_SECRET is not defined");
+  }
+  if (!scopes) {
+    throw new Error("SHOPIFY_APP_SCOPES is not defined");
+  }
+  let hostname;
+  try {
+    const normalizedUrl = appUrl.startsWith("http") ? appUrl : `https://${appUrl}`;
+    hostname = new URL(normalizedUrl).hostname;
+  } catch {
+    throw new Error(`Invalid SHOPIFY_APP_URL: ${appUrl}`);
+  }
+  shopifyApiInstance = shopifyApi({
+    apiKey,
+    apiSecretKey: apiSecret,
+    scopes: scopes.split(","),
+    hostName: hostname,
+    hostScheme: "https",
+    apiVersion: ApiVersion.October25,
+    isEmbeddedApp: true
+  });
+  return shopifyApiInstance;
+}

package/dist/runtime/server/utils/useShopifyGraphQL.d.ts

@@ -0,0 +1,2 @@
+import type { GraphqlClient } from '@shopify/shopify-api';
+export declare function useShopifyGraphQL(shop: string, accessToken: string): GraphqlClient;

package/dist/runtime/server/utils/useShopifyGraphQL.js

@@ -0,0 +1,30 @@
+import { useRuntimeConfig } from "#imports";
+import { useShopifyAPI } from "./useShopifyAPI.js";
+export function useShopifyGraphQL(shop, accessToken) {
+  const config = useRuntimeConfig();
+  const shopify = useShopifyAPI();
+  return new shopify.clients.Graphql({
+    session: {
+      id: `offline_${shop}`,
+      shop,
+      state: "",
+      isOnline: false,
+      accessToken,
+      scope: config.shopifyEmbedded.scopes,
+      isActive: () => true,
+      isScopeChanged: () => false,
+      isScopeIncluded: () => true,
+      isExpired: () => false,
+      equals: () => false,
+      toObject: () => ({
+        id: `offline_${shop}`,
+        shop,
+        state: "",
+        isOnline: false,
+        accessToken,
+        scope: config.shopifyEmbedded.scopes
+      })
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+  });
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "nuxt-shopify-embedded",
+  "version": "0.1.4",
+  "description": "Nuxt module for building Shopify embedded apps with Polaris components, App Bridge, and GraphQL client",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@10.22.0",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "types": "./dist/types.d.mts",
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qvdp/nuxt-shopify-embedded.git"
+  },
+  "homepage": "https://github.com/qvdp/nuxt-shopify-embedded#readme",
+  "bugs": {
+    "url": "https://github.com/qvdp/nuxt-shopify-embedded/issues"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "nuxt4",
+    "shopify",
+    "shopify-app",
+    "shopify-embedded-app",
+    "shopify-marketplace",
+    "polaris",
+    "app-bridge",
+    "graphql",
+    "vue",
+    "vue3",
+    "nitro"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:shopify": "cd playground && shopify app dev",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@shopify/shopify-api": "^12.3.0",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/eslint-config": "^1.13.0",
+    "@nuxt/kit": "^4.3.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.0",
+    "@nuxt/test-utils": "^3.23.0",
+    "@shopify/app-bridge-types": "^0.5.3",
+    "@shopify/polaris-types": "^1.0.1",
+    "@types/node": "^25.0.10",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.2",
+    "nuxt": "^4.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4"
+  }
+}