feat: add middleware and types documentation for Shopify authentication

Author: yan-ad

docs/content/3.api/4.middleware.md

@@ -0,0 +1,151 @@
+---
+title: Middleware
+description: Client-side route middleware for Shopify authentication and the built-in login page.
+navigation:
+  icon: i-lucide-shield-check
+seo:
+  title: Middleware — shopify-app-nuxt API Reference
+  description: Reference for the shopify-auth route middleware and the default auth-login page component.
+---
+
+## `shopify-auth`
+
+A **named** Nuxt route middleware that guards pages requiring an authenticated Shopify session. It is auto-registered by the module but **not global** — you opt-in per page.
+
+### How It Works
+
+| Environment | Check | Redirect |
+| --- | --- | --- |
+| **Server (SSR)** | Looks for the `shop` query parameter that Shopify always provides when loading an embedded app | Redirects to the auth page if missing |
+| **Client** | Checks `window.shopify.config.shop` from App Bridge | Redirects to the auth page if unavailable |
+
+If the check fails on either side, the middleware navigates to the auth page (default `/auth`). The path is configurable via `authPagePath` in the public runtime config.
+
+### Usage
+
+Add `definePageMeta({ middleware: 'shopify-auth' })` to any page that should require authentication:
+
+```vue
+<script setup>
+definePageMeta({
+  middleware: 'shopify-auth'
+})
+</script>
+
+<template>
+  <ShPage title="Dashboard">
+    <!-- Only renders when authenticated -->
+  </ShPage>
+</template>
+```
+
+You can also apply it to a layout if all pages under that layout need protection:
+
+```vue
+<!-- layouts/default.vue -->
+<script setup>
+definePageMeta({
+  middleware: 'shopify-auth'
+})
+</script>
+
+<template>
+  <ShopifyAppProvider>
+    <slot />
+  </ShopifyAppProvider>
+</template>
+```
+
+### Source
+
+```ts
+defineNuxtRouteMiddleware((to) => {
+  const config = useRuntimeConfig().public.shopify
+  const authPage = config.authPagePath || '/auth'
+
+  if (import.meta.server) {
+    const shop = to.query.shop as string | undefined
+    if (!shop) return navigateTo(authPage)
+    return
+  }
+
+  const shop = window.shopify?.config?.shop
+  if (!shop) return navigateTo(authPage)
+})
+```
+
+---
+
+## Default Auth Login Page
+
+The module ships a built-in `/auth` page (`auth-login.vue`) that provides a styled login form for merchants. It is automatically registered unless explicitly disabled.
+
+### What It Does
+
+1. Presents a centered card with the Shopify logo, a shop domain input field, and a **Log in** button
+2. Accepts a bare store name (e.g., `my-shop`) or a full domain (`my-shop.myshopify.com`)
+3. On submit, redirects the merchant to the OAuth flow at `{authPathPrefix}?shop={domain}`
+
+### Appearance
+
+The page renders with `layout: false` (no app shell) and uses self-contained scoped styles that match the Shopify admin aesthetic — no Polaris dependency required.
+
+### Controlling the Auth Page
+
+The `authPage` module option controls this page:
+
+| Value | Behavior |
+| --- | --- |
+| *(not set)* | Registers the default `auth-login.vue` at `/auth` |
+| `false` | Disables the built-in page entirely — you must handle the route yourself |
+| `'/path/to/MyLogin.vue'` | Registers your custom component at `/auth` instead |
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  shopify: {
+    // Use defaults (built-in login page at /auth)
+    // authPage: undefined
+
+    // Disable the built-in page
+    // authPage: false
+
+    // Use a custom component
+    // authPage: '~/components/MyShopifyLogin.vue'
+  }
+})
+```
+
+### Overriding the Page
+
+To fully customize the login experience while keeping the same route, create your own component and point `authPage` to it. Your component should:
+
+1. Collect the shop domain from the merchant
+2. Redirect to `{authPathPrefix}?shop={domain}` with `external: true`
+
+```vue
+<!-- components/MyShopifyLogin.vue -->
+<script setup>
+definePageMeta({ layout: false })
+
+const shop = ref('')
+const config = useRuntimeConfig()
+
+function login() {
+  const domain = shop.value.includes('.myshopify.com')
+    ? shop.value
+    : `${shop.value}.myshopify.com`
+  navigateTo(
+    `${config.public.shopify.authPathPrefix}?shop=${encodeURIComponent(domain)}`,
+    { external: true }
+  )
+}
+</script>
+
+<template>
+  <form @submit.prevent="login">
+    <input v-model="shop" placeholder="your-shop" />
+    <button type="submit">Install</button>
+  </form>
+</template>
+```