create-partylayer-app 0.1.1 → 0.3.0

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,SAAS,EAAE,YAAY,EAMnC,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,SAAS,EAAE,YAAY,EAgBnC,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/templates.js

@@ -4,6 +4,16 @@ export const TEMPLATES = [
         label: 'React + Vite',
         hint: 'React 18, Vite, zero-config PartyLayerKit',
     },
+    {
+        id: 'next-ssr',
+        label: 'Next.js (SSR)',
+        hint: 'App Router, server-side session via cookieStorage',
+    },
+    {
+        id: 'vue-nuxt-pinia',
+        label: 'Vue + Nuxt + Pinia',
+        hint: 'Nuxt 3 SSR session, PartyLayer session in a Pinia store',
+    },
 ];
 export function isTemplateId(value) {
     return TEMPLATES.some((t) => t.id === value);

package/dist/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,2CAA2C;KAClD;CACF,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,2CAA2C;KAClD;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,mDAAmD;KAC1D;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,yDAAyD;KAChE;CACF,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-partylayer-app",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Scaffold a PartyLayer dApp (Canton wallet integration) in seconds.",
   "type": "module",
   "bin": {

package/templates/next-ssr/README.md

@@ -0,0 +1,28 @@
+# {{PROJECT_NAME}}
+
+A [PartyLayer](https://partylayer.xyz) dApp — Next.js App Router with **SSR session**.
+
+## Develop
+
+```bash
+npm run dev
+```
+
+## How SSR session works
+
+- **Server** ([lib/session.ts](lib/session.ts)) reads the session cookie via `next/headers` `cookies()` + `@partylayer/session`'s `createCookieStorage` → the connected party is rendered in the **initial HTML** (no disconnected→connected flash). `app/page.tsx` is a Server Component that gates on `getServerSession()`.
+- **Client** ([app/providers.tsx](app/providers.tsx)) wraps the app in `PartyLayerKit` with `sessionOptions={{ storage: createCookieStorage() }}` — `document.cookie` (synchronous), the **same** cookie the server reads.
+- `next/headers` is imported only in your app (`lib/session.ts`), never in `@partylayer/session` — the library stays framework-agnostic.
+
+Switch networks by changing `network` in `app/providers.tsx` and `appName` accordingly.
+
+## Build
+
+```bash
+npm run build && npm start
+```
+
+## Docs
+
+- [PartyLayer docs](https://partylayer.xyz/docs/introduction)
+- [@partylayer/session — createCookieStorage](https://www.npmjs.com/package/@partylayer/session)

package/templates/next-ssr/_gitignore

@@ -0,0 +1,10 @@
+node_modules
+.next
+out
+build
+*.local
+.DS_Store
+.env
+.env.*
+!.env.example
+next-env.d.ts

package/templates/next-ssr/_package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@partylayer/react": "^0.9.1",
+    "@partylayer/sdk": "^0.10.0",
+    "@partylayer/session": "^1.1.0",
+    "next": "^14.2.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "typescript": "^5.6.2"
+  }
+}

package/templates/next-ssr/app/globals.css

@@ -0,0 +1,42 @@
+:root {
+  color-scheme: light dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  background: #0b0f1a;
+  color: rgba(255, 255, 255, 0.92);
+}
+
+.app {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 24px;
+  text-align: center;
+}
+
+.app h1 {
+  font-size: 2.5rem;
+  margin: 0;
+}
+
+.subtitle {
+  margin: 0 0 8px;
+  color: rgba(255, 255, 255, 0.6);
+  max-width: 32rem;
+}
+
+.session code {
+  background: rgba(255, 255, 255, 0.08);
+  padding: 2px 8px;
+  border-radius: 6px;
+}

package/templates/next-ssr/app/layout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { Providers } from './providers';
+import './globals.css';
+
+export const metadata = {
+  title: '{{PROJECT_NAME}}',
+  description: 'A PartyLayer dApp on Canton (Next.js App Router + SSR session).',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/next-ssr/app/page.tsx

@@ -0,0 +1,33 @@
+import { getServerSession, truncateParty } from '@/lib/session';
+import { ConnectButton } from '@/components/ConnectButton';
+
+// Reading cookies() opts this route into dynamic (per-request) rendering — which
+// is exactly what SSR session needs: the server reads the session cookie on
+// every request and renders the connected state into the initial HTML.
+export default function Home() {
+  const session = getServerSession();
+  const party = session?.account?.partyId ?? null;
+
+  return (
+    <main className="app">
+      <h1>{{PROJECT_NAME}}</h1>
+      <p className="subtitle">A PartyLayer dApp on Canton — connect any verified wallet.</p>
+
+      {/* SERVER-RENDERED connected state (Option A: server owns the display). This
+          appears in the initial HTML from the cookie, before any client JS, so
+          there is no disconnected→connected flash. */}
+      {party ? (
+        <p className="session">
+          Connected as <code data-testid="server-party">{truncateParty(party)}</code>
+        </p>
+      ) : (
+        <p className="session" data-testid="server-cta">
+          Not connected — connect a wallet to continue.
+        </p>
+      )}
+
+      {/* Interactive client island — reconciles silently with the live provider. */}
+      <ConnectButton />
+    </main>
+  );
+}

package/templates/next-ssr/app/providers.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { useMemo, type ReactNode } from 'react';
+import { PartyLayerKit } from '@partylayer/react';
+import { createCookieStorage } from '@partylayer/session';
+
+/**
+ * Client provider boundary. cookieStorage on the client uses document.cookie
+ * (synchronous → flash-free), the SAME cookie the server reads in lib/session.ts
+ * — so server HTML and client hydration agree.
+ */
+export function Providers({ children }: { children: ReactNode }) {
+  const storage = useMemo(() => createCookieStorage(), []);
+  return (
+    <PartyLayerKit network="devnet" appName="{{PROJECT_NAME}}" sessionOptions={{ storage }}>
+      {children}
+    </PartyLayerKit>
+  );
+}

package/templates/next-ssr/components/ConnectButton.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import { ConnectButton as PartyLayerConnectButton } from '@partylayer/react';
+
+/** Client island: the full connect flow (modal → connected state → disconnect). */
+export function ConnectButton() {
+  return <PartyLayerConnectButton />;
+}

package/templates/next-ssr/lib/session.ts

@@ -0,0 +1,41 @@
+import { cookies } from 'next/headers';
+import {
+  createCookieStorage,
+  decodeSessionEnvelope,
+  type CookieAdapter,
+  type PersistedSessionSnapshot,
+} from '@partylayer/session';
+
+// next/headers is imported HERE (the app), never inside @partylayer/session —
+// the library stays framework-agnostic. This adapter wraps Next's read-only
+// request cookies into the CookieAdapter shape createCookieStorage expects.
+function nextCookieAdapter(): CookieAdapter {
+  const jar = cookies();
+  return {
+    get: (name) => jar.get(name)?.value ?? null,
+    // Server Components can only READ cookies; writes happen client-side
+    // (document.cookie) or in a Route Handler / Server Action.
+    set: () => {},
+    remove: () => {},
+  };
+}
+
+/**
+ * Read the persisted session ON THE SERVER (for SSR). Returns the decoded
+ * snapshot (party, network, …) or null. This is what lets a Server Component
+ * render the connected state in the initial HTML — before any client JS.
+ */
+export function getServerSession(): PersistedSessionSnapshot | null {
+  const storage = createCookieStorage({ adapter: nextCookieAdapter() });
+  // Cookie reads are synchronous; the SessionStorage interface types getItem as
+  // string | null | Promise, so narrow to a string (null/absent → no session).
+  const raw = storage.getItem('pl_session');
+  if (typeof raw !== 'string') return null;
+  return decodeSessionEnvelope(raw);
+}
+
+/** Pure, server-safe party-id truncation (avoids importing a client module). */
+export function truncateParty(partyId: string): string {
+  if (partyId.length <= 16) return partyId;
+  return `${partyId.slice(0, 10)}…${partyId.slice(-4)}`;
+}

package/templates/next-ssr/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;

package/templates/next-ssr/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/vue-nuxt-pinia/README.md

@@ -0,0 +1,27 @@
+# {{PROJECT_NAME}}
+
+A [PartyLayer](https://partylayer.xyz) dApp — Nuxt 3 + Vue 3 + Pinia, with **SSR session**.
+
+## Develop
+
+```bash
+npm run dev
+```
+
+## How it's wired
+
+- **Server** ([lib/session.ts](lib/session.ts)) reads the session cookie via Nuxt's SSR-aware `useCookie()`, wrapped as a `CookieAdapter` and fed to `@partylayer/session`'s `createCookieStorage` → the connected party renders in the **initial HTML** (no flash). `app.vue` gates on `getServerSession()`.
+- **Client** ([plugins/partylayer.client.ts](plugins/partylayer.client.ts)) creates the PartyLayer client and provides the session store (`createPartyLayerSession`), using `createCookieStorage()` (the same cookie, `document.cookie`).
+- **Pinia** ([stores/session.ts](stores/session.ts)) surfaces the PartyLayer session (`isConnected` / `party` / `status` + `connect`/`disconnect`) as a store — components read the store. This is the idiomatic "PartyLayer + Pinia" pattern.
+- Nuxt's cookie API is used only in your app (`lib/session.ts`), never in `@partylayer/session` — the library stays framework-agnostic (the same `CookieAdapter` the Next template feeds with `cookies()`).
+
+## Build
+
+```bash
+npm run build && npm run preview
+```
+
+## Docs
+
+- [PartyLayer docs](https://partylayer.xyz/docs/introduction)
+- [@partylayer/vue composables](https://www.npmjs.com/package/@partylayer/vue)

package/templates/vue-nuxt-pinia/_gitignore

@@ -0,0 +1,10 @@
+node_modules
+.nuxt
+.output
+.data
+dist
+*.local
+.DS_Store
+.env
+.env.*
+!.env.example

package/templates/vue-nuxt-pinia/_package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "preview": "nuxt preview",
+    "generate": "nuxt generate",
+    "postinstall": "nuxt prepare"
+  },
+  "dependencies": {
+    "@partylayer/sdk": "^0.10.0",
+    "@partylayer/session": "^1.1.0",
+    "@partylayer/vue": "^0.1.3",
+    "@pinia/nuxt": "^0.5.5",
+    "pinia": "^2.2.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "nuxt": "^3.13.0"
+  }
+}

package/templates/vue-nuxt-pinia/app.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import { getServerSession, truncateParty } from './lib/session';
+import { useSessionStore } from './stores/session';
+
+// SSR-aware cookie → server-rendered connected party (Option A: the server owns
+// the display, so there's no disconnected→connected flash in the initial HTML).
+const cookie = useCookie<string | null>('pl_session');
+const session = getServerSession(cookie);
+const serverParty = session?.account?.partyId ?? null;
+
+// Pinia store = the reactive client session (the interactive island).
+const sessionStore = useSessionStore();
+</script>
+
+<template>
+  <main class="app">
+    <h1>{{PROJECT_NAME}}</h1>
+    <p class="subtitle">A PartyLayer dApp on Canton — Nuxt 3 + Pinia, SSR session.</p>
+
+    <!-- SERVER-RENDERED party from the cookie (initial HTML, no flash) -->
+    <p v-if="serverParty" class="session">
+      Connected as <code data-testid="server-party">{{ truncateParty(serverParty) }}</code>
+    </p>
+    <p v-else class="session" data-testid="server-cta">
+      Not connected — connect a wallet to continue.
+    </p>
+
+    <!-- Pinia-backed interactive session (reads the Pinia store, not the composables) -->
+    <button v-if="!sessionStore.isConnected" class="btn" @click="sessionStore.connect()">
+      Connect Wallet
+    </button>
+    <div v-else class="connected">
+      <code>{{ truncateParty(sessionStore.party ?? '') }}</code>
+      <button class="btn" @click="sessionStore.disconnect()">Disconnect</button>
+    </div>
+  </main>
+</template>
+
+<style>
+:root { color-scheme: light dark; }
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  background: #0b0f1a;
+  color: rgba(255, 255, 255, 0.92);
+}
+.app {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 24px;
+  text-align: center;
+}
+.app h1 { font-size: 2.5rem; margin: 0; }
+.subtitle { margin: 0 0 8px; color: rgba(255, 255, 255, 0.6); max-width: 32rem; }
+.session code, .connected code {
+  background: rgba(255, 255, 255, 0.08);
+  padding: 2px 8px;
+  border-radius: 6px;
+}
+.btn {
+  padding: 10px 18px;
+  border-radius: 8px;
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  background: #ffcc00;
+  color: #0b0f1a;
+  font-weight: 600;
+  cursor: pointer;
+}
+</style>

package/templates/vue-nuxt-pinia/lib/session.ts

@@ -0,0 +1,46 @@
+import {
+  createCookieStorage,
+  decodeSessionEnvelope,
+  type CookieAdapter,
+  type PersistedSessionSnapshot,
+} from '@partylayer/session';
+import type { Ref } from 'vue';
+
+/**
+ * Wrap a Nuxt `useCookie()` ref as a `CookieAdapter`. `useCookie` is SSR-aware:
+ * on the server it reads the request's Cookie header, on the client it reads
+ * `document.cookie`. This is the SAME `CookieAdapter` interface next-ssr feeds
+ * with `next/headers` `cookies()` — different framework, one primitive. Nuxt's
+ * cookie API lives ONLY here (the app), never inside `@partylayer/session`.
+ */
+export function nuxtCookieAdapter(cookieRef: Ref<string | null | undefined>): CookieAdapter {
+  return {
+    get: () => cookieRef.value ?? null,
+    set: (_name, value) => {
+      cookieRef.value = value;
+    },
+    remove: () => {
+      cookieRef.value = null;
+    },
+  };
+}
+
+/**
+ * Read the persisted session on the server (for SSR) from the cookie ref, so a
+ * page can render the connected party in the initial HTML — before any client JS.
+ */
+export function getServerSession(
+  cookieRef: Ref<string | null | undefined>,
+): PersistedSessionSnapshot | null {
+  const storage = createCookieStorage({ adapter: nuxtCookieAdapter(cookieRef) });
+  // Cookie reads are synchronous; narrow the MaybePromise interface type.
+  const raw = storage.getItem('pl_session');
+  if (typeof raw !== 'string') return null;
+  return decodeSessionEnvelope(raw);
+}
+
+/** Pure, server-safe party-id truncation. */
+export function truncateParty(partyId: string): string {
+  if (partyId.length <= 16) return partyId;
+  return `${partyId.slice(0, 10)}…${partyId.slice(-4)}`;
+}

package/templates/vue-nuxt-pinia/nuxt.config.ts

@@ -0,0 +1,6 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  modules: ['@pinia/nuxt'],
+  compatibilityDate: '2024-11-01',
+  devtools: { enabled: false },
+});

package/templates/vue-nuxt-pinia/plugins/partylayer.client.ts

@@ -0,0 +1,19 @@
+import { createPartyLayer } from '@partylayer/sdk';
+import { createPartyLayerSession } from '@partylayer/vue';
+import { createCookieStorage } from '@partylayer/session';
+
+/**
+ * Client-only plugin: create the PartyLayer client and provide the session store
+ * app-wide. cookieStorage on the client uses document.cookie — the SAME cookie
+ * the server reads for SSR (lib/session.ts). The connected/wallet UI is
+ * client-side; the server-rendered party comes from the cookie directly.
+ */
+export default defineNuxtPlugin((nuxtApp) => {
+  const client = createPartyLayer({ network: 'devnet', app: { name: '{{PROJECT_NAME}}' } });
+  nuxtApp.vueApp.use(
+    createPartyLayerSession({
+      provider: client.asProvider(),
+      storage: createCookieStorage(),
+    }),
+  );
+});

package/templates/vue-nuxt-pinia/stores/session.ts

@@ -0,0 +1,16 @@
+import { defineStore } from 'pinia';
+import { useSession, useAccount } from '@partylayer/vue';
+
+/**
+ * Pinia store surfacing the PartyLayer session — the idiomatic
+ * "PartyLayer + Pinia" pattern. Components read THIS store instead of the
+ * composables directly. The composables are SSR-safe (with no provided store
+ * they report a disconnected session), so this store is safe during SSR too;
+ * the live state comes in on the client once the plugin provides the store.
+ */
+export const useSessionStore = defineStore('partylayer-session', () => {
+  const { status, isConnected, isConnecting, connect, disconnect } = useSession();
+  const { party, networkId } = useAccount();
+
+  return { status, isConnected, isConnecting, party, networkId, connect, disconnect };
+});

package/templates/vue-nuxt-pinia/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  // https://nuxt.com/docs/guide/concepts/typescript
+  "extends": "./.nuxt/tsconfig.json"
+}