@blu1606/create-walrus-app 0.1.0

package/templates/base/src/utils/env.ts

@@ -0,0 +1,41 @@
+export interface EnvConfig {
+  walrusNetwork: string;
+  walrusAggregator: string;
+  walrusPublisher: string;
+  suiNetwork: string;
+  suiRpc: string;
+  blockberryKey?: string;
+}
+
+export function loadEnv(): EnvConfig {
+  const getEnv = (key: string, required = true): string => {
+    const value = import.meta.env[key];
+    if (required && !value) {
+      throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value || '';
+  };
+
+  return {
+    walrusNetwork: getEnv('VITE_WALRUS_NETWORK'),
+    walrusAggregator: getEnv('VITE_WALRUS_AGGREGATOR'),
+    walrusPublisher: getEnv('VITE_WALRUS_PUBLISHER'),
+    suiNetwork: getEnv('VITE_SUI_NETWORK'),
+    suiRpc: getEnv('VITE_SUI_RPC'),
+    blockberryKey: getEnv('VITE_BLOCKBERRY_KEY', false),
+  };
+}
+
+export function validateEnv(config: EnvConfig): void {
+  if (!['testnet', 'mainnet', 'devnet'].includes(config.walrusNetwork)) {
+    throw new Error(`Invalid WALRUS_NETWORK: ${config.walrusNetwork}`);
+  }
+
+  if (!config.walrusAggregator.startsWith('http')) {
+    throw new Error('WALRUS_AGGREGATOR must be a valid HTTP URL');
+  }
+
+  if (!config.walrusPublisher.startsWith('http')) {
+    throw new Error('WALRUS_PUBLISHER must be a valid HTTP URL');
+  }
+}

package/templates/base/src/utils/format.ts

@@ -0,0 +1,29 @@
+/**
+ * Format bytes to human-readable size
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+/**
+ * Format blob ID for display (truncate middle)
+ */
+export function formatBlobId(blobId: string, length = 12): string {
+  if (blobId.length <= length) return blobId;
+
+  const part = Math.floor((length - 3) / 2);
+  return `${blobId.slice(0, part)}...${blobId.slice(-part)}`;
+}
+
+/**
+ * Format timestamp to locale string
+ */
+export function formatDate(timestamp: number): string {
+  return new Date(timestamp).toLocaleString();
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/gallery/README.md

@@ -0,0 +1,44 @@
+# File Gallery Use Case
+
+Manage multiple files with a persistent index.
+
+## Features
+
+- Upload multiple files
+- Grid view of all files
+- Local index (localStorage)
+- Delete files from gallery
+- File metadata display
+
+## Index Format
+
+```json
+{
+  "version": "1.0",
+  "items": [
+    {
+      "blobId": "abc123...",
+      "name": "photo.jpg",
+      "size": 102400,
+      "contentType": "image/jpeg",
+      "uploadedAt": 1705449600000
+    }
+  ],
+  "lastModified": 1705449600000
+}
+```
+
+## Usage
+
+1. Click "Choose File" to select a file
+2. Click "Add to Gallery" to upload
+3. Files appear in the grid below
+4. Click "Delete" to remove files from gallery
+
+## Code Structure
+
+- `GalleryGrid.tsx` - Grid layout for files
+- `FileCard.tsx` - Individual file display
+- `UploadModal.tsx` - Upload UI
+- `index-manager.ts` - localStorage persistence
+- `gallery.ts` - Type definitions

package/templates/gallery/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {}
+}

package/templates/gallery/src/App.tsx

@@ -0,0 +1,21 @@
+import { useState } from 'react';
+import { Layout } from '../../react/src/components/Layout.js';
+import { GalleryGrid } from './components/GalleryGrid.js';
+import { UploadModal } from './components/UploadModal.js';
+import './styles.css';
+
+function App() {
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  return (
+    <Layout>
+      <div className="gallery-app">
+        <h2>🖼️ File Gallery</h2>
+        <UploadModal onSuccess={() => setRefreshKey((k) => k + 1)} />
+        <GalleryGrid key={refreshKey} />
+      </div>
+    </Layout>
+  );
+}
+
+export default App;

package/templates/gallery/src/components/FileCard.tsx

@@ -0,0 +1,27 @@
+import { formatBytes, formatDate } from '../../../base/src/utils/format.js';
+import { removeItem } from '../utils/index-manager.js';
+import type { GalleryItem } from '../types/gallery.js';
+
+interface FileCardProps {
+  item: GalleryItem;
+  onDelete: () => void;
+}
+
+export function FileCard({ item, onDelete }: FileCardProps) {
+  const handleDelete = () => {
+    if (confirm(`Delete ${item.name}?`)) {
+      removeItem(item.blobId);
+      onDelete();
+    }
+  };
+
+  return (
+    <div className="file-card">
+      <h4>{item.name}</h4>
+      <p>Size: {formatBytes(item.size)}</p>
+      <p>Uploaded: {formatDate(item.uploadedAt)}</p>
+      <p className="blob-id">Blob ID: {item.blobId.slice(0, 12)}...</p>
+      <button onClick={handleDelete}>Delete</button>
+    </div>
+  );
+}

package/templates/gallery/src/components/GalleryGrid.tsx

@@ -0,0 +1,30 @@
+import { useState, useEffect } from 'react';
+import { FileCard } from './FileCard.js';
+import { loadIndex } from '../utils/index-manager.js';
+import type { GalleryItem } from '../types/gallery.js';
+
+export function GalleryGrid() {
+  const [items, setItems] = useState<GalleryItem[]>([]);
+
+  useEffect(() => {
+    const index = loadIndex();
+    setItems(index.items);
+  }, []);
+
+  const refreshGallery = () => {
+    const index = loadIndex();
+    setItems(index.items);
+  };
+
+  return (
+    <div className="gallery-grid">
+      {items.length === 0 ? (
+        <p>No files yet. Upload your first file!</p>
+      ) : (
+        items.map((item) => (
+          <FileCard key={item.blobId} item={item} onDelete={refreshGallery} />
+        ))
+      )}
+    </div>
+  );
+}

package/templates/gallery/src/components/UploadModal.tsx

@@ -0,0 +1,45 @@
+import { useState } from 'react';
+import { useUpload } from '../../../react/src/hooks/useStorage.js';
+import { addItem } from '../utils/index-manager.js';
+
+interface UploadModalProps {
+  onSuccess: () => void;
+}
+
+export function UploadModal({ onSuccess }: UploadModalProps) {
+  const [file, setFile] = useState<File | null>(null);
+  const upload = useUpload();
+
+  const handleUpload = async () => {
+    if (!file) return;
+
+    upload.mutate(
+      { file, options: { epochs: 1 } },
+      {
+        onSuccess: async (data) => {
+          addItem({
+            blobId: data.blobId,
+            name: file.name,
+            size: file.size,
+            contentType: file.type,
+            uploadedAt: Date.now(),
+          });
+          setFile(null);
+          onSuccess();
+        },
+      }
+    );
+  };
+
+  return (
+    <div className="upload-modal">
+      <input
+        type="file"
+        onChange={(e) => setFile(e.target.files?.[0] || null)}
+      />
+      <button onClick={handleUpload} disabled={!file || upload.isPending}>
+        {upload.isPending ? 'Uploading...' : 'Add to Gallery'}
+      </button>
+    </div>
+  );
+}

package/templates/gallery/src/styles.css

@@ -0,0 +1,58 @@
+.gallery-app {
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+.upload-modal {
+  margin: 2rem 0;
+  padding: 1.5rem;
+  border: 1px solid #333;
+  border-radius: 8px;
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+
+.gallery-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.file-card {
+  padding: 1.5rem;
+  border: 1px solid #333;
+  border-radius: 8px;
+  background: #1a1a1a;
+}
+
+.file-card h4 {
+  margin: 0 0 1rem 0;
+  color: #fff;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.file-card p {
+  margin: 0.5rem 0;
+  font-size: 0.9rem;
+  color: #aaa;
+}
+
+.file-card .blob-id {
+  font-family: monospace;
+  font-size: 0.8rem;
+  color: #888;
+}
+
+.file-card button {
+  margin-top: 1rem;
+  width: 100%;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/templates/gallery/src/types/gallery.ts

@@ -0,0 +1,13 @@
+export interface GalleryItem {
+  blobId: string;
+  name: string;
+  size: number;
+  contentType: string;
+  uploadedAt: number;
+}
+
+export interface GalleryIndex {
+  version: '1.0';
+  items: GalleryItem[];
+  lastModified: number;
+}

package/templates/gallery/src/utils/index-manager.ts

@@ -0,0 +1,37 @@
+import type { GalleryIndex, GalleryItem } from '../types/gallery.js';
+
+const INDEX_KEY = 'gallery-index';
+
+export function loadIndex(): GalleryIndex {
+  try {
+    const stored = localStorage.getItem(INDEX_KEY);
+    if (!stored) {
+      return { version: '1.0', items: [], lastModified: Date.now() };
+    }
+    const parsed = JSON.parse(stored);
+    if (!parsed.version || !Array.isArray(parsed.items)) {
+      throw new Error('Invalid index format');
+    }
+    return parsed;
+  } catch (error) {
+    console.warn('Failed to load gallery index, resetting:', error);
+    return { version: '1.0', items: [], lastModified: Date.now() };
+  }
+}
+
+export function saveIndex(index: GalleryIndex): void {
+  index.lastModified = Date.now();
+  localStorage.setItem(INDEX_KEY, JSON.stringify(index));
+}
+
+export function addItem(item: GalleryItem): void {
+  const index = loadIndex();
+  index.items.push(item);
+  saveIndex(index);
+}
+
+export function removeItem(blobId: string): void {
+  const index = loadIndex();
+  index.items = index.items.filter((item) => item.blobId !== blobId);
+  saveIndex(index);
+}

package/templates/react/.eslintrc.json

@@ -0,0 +1,26 @@
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "plugins": ["@typescript-eslint", "react", "react-hooks"],
+  "rules": {
+    "no-console": "warn",
+    "react/react-in-jsx-scope": "off"
+  },
+  "settings": {
+    "react": {
+      "version": "detect"
+    }
+  }
+}

package/templates/react/README.md

@@ -0,0 +1,80 @@
+# React + Vite Framework Layer
+
+Modern React 18 application with Vite build system.
+
+## Features
+
+✅ **React 18** - Hooks, Suspense, Concurrent features  
+✅ **Vite 5** - Lightning-fast HMR and builds  
+✅ **TanStack Query** - Async state management  
+✅ **@mysten/dapp-kit** - Sui wallet integration  
+✅ **TypeScript** - Full type safety
+
+## Project Structure
+
+```
+src/
+├── components/     # Reusable UI components
+├── providers/      # Context providers
+├── hooks/          # Custom React hooks
+├── App.tsx         # Root component
+└── main.tsx        # Entry point
+```
+
+## Custom Hooks
+
+### `useUpload()`
+
+Upload files to Walrus:
+
+```typescript
+const upload = useUpload();
+
+upload.mutate({ file: myFile, options: { epochs: 1 } });
+```
+
+### `useDownload(blobId)`
+
+Download blob data:
+
+```typescript
+const { data, isLoading } = useDownload(blobId);
+```
+
+### `useMetadata(blobId)`
+
+Fetch blob metadata:
+
+```typescript
+const { data: metadata } = useMetadata(blobId);
+console.log(`Size: ${metadata.size} bytes`);
+```
+
+### `useWallet()`
+
+Access wallet state:
+
+```typescript
+const { isConnected, address } = useWallet();
+```
+
+## Development
+
+```bash
+npm run dev        # Start dev server (http://localhost:3000)
+npm run build      # Build for production
+npm run preview    # Preview production build
+```
+
+## Wallet Setup
+
+1. Install Sui Wallet browser extension
+2. Get testnet SUI from faucet
+3. Connect wallet in the app
+
+## Resources
+
+- [React Docs](https://react.dev)
+- [Vite Docs](https://vitejs.dev)
+- [TanStack Query](https://tanstack.com/query)
+- [@mysten/dapp-kit](https://sdk.mystenlabs.com/dapp-kit)

package/templates/react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Walrus App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext .ts,.tsx",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@tanstack/react-query": "^5.17.0",
+    "@mysten/dapp-kit": "^0.14.0",
+    "@mysten/sui": "^1.10.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.48",
+    "@types/react-dom": "^18.2.18",
+    "@vitejs/plugin-react": "^4.2.1",
+    "vite": "^5.0.11",
+    "typescript": "^5.3.3",
+    "eslint": "^8.56.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0"
+  }
+}

package/templates/react/src/App.tsx

@@ -0,0 +1,14 @@
+import { Layout } from './components/Layout.js';
+
+function App() {
+  return (
+    <Layout>
+      <div className="welcome">
+        <h2>Welcome to Walrus Starter Kit</h2>
+        <p>This app will be customized by the use case layer</p>
+      </div>
+    </Layout>
+  );
+}
+
+export default App;

package/templates/react/src/components/Layout.tsx

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { WalletConnect } from './WalletConnect.js';
+
+interface LayoutProps {
+  children: ReactNode;
+}
+
+export function Layout({ children }: LayoutProps) {
+  return (
+    <div className="app-layout">
+      <header className="app-header">
+        <h1>🌊 Walrus App</h1>
+        <WalletConnect />
+      </header>
+      <main className="app-main">{children}</main>
+      <footer className="app-footer">
+        <p>Powered by Walrus & Sui</p>
+      </footer>
+    </div>
+  );
+}

package/templates/react/src/components/WalletConnect.tsx

@@ -0,0 +1,21 @@
+import { ConnectButton } from '@mysten/dapp-kit';
+import { useWallet } from '../hooks/useWallet.js';
+
+export function WalletConnect() {
+  const { isConnected, address } = useWallet();
+
+  return (
+    <div className="wallet-connect">
+      {isConnected ? (
+        <div className="wallet-info">
+          <span>
+            Connected: {address?.slice(0, 6)}...{address?.slice(-4)}
+          </span>
+        </div>
+      ) : (
+        <p>Please connect your wallet</p>
+      )}
+      <ConnectButton />
+    </div>
+  );
+}

package/templates/react/src/dapp-kit.css

@@ -0,0 +1 @@
+@import '@mysten/dapp-kit/dist/index.css';

package/templates/react/src/hooks/useStorage.ts

@@ -0,0 +1,40 @@
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { storageAdapter } from '../index.js';
+import type { UploadOptions } from '../adapters/storage.js';
+
+export function useUpload() {
+  return useMutation({
+    mutationFn: async ({
+      file,
+      options,
+    }: {
+      file: File;
+      options?: UploadOptions;
+    }) => {
+      const blobId = await storageAdapter.upload(file, options);
+      return { blobId, file };
+    },
+  });
+}
+
+export function useDownload(blobId: string | null) {
+  return useQuery({
+    queryKey: ['blob', blobId],
+    queryFn: async () => {
+      if (!blobId) throw new Error('No blob ID provided');
+      return await storageAdapter.download(blobId);
+    },
+    enabled: !!blobId,
+  });
+}
+
+export function useMetadata(blobId: string | null) {
+  return useQuery({
+    queryKey: ['metadata', blobId],
+    queryFn: async () => {
+      if (!blobId) throw new Error('No blob ID provided');
+      return await storageAdapter.getMetadata(blobId);
+    },
+    enabled: !!blobId,
+  });
+}

package/templates/react/src/hooks/useWallet.ts

@@ -0,0 +1,16 @@
+import {
+  useCurrentAccount,
+  useSignAndExecuteTransaction,
+} from '@mysten/dapp-kit';
+
+export function useWallet() {
+  const currentAccount = useCurrentAccount();
+  const { mutate: signAndExecute } = useSignAndExecuteTransaction();
+
+  return {
+    account: currentAccount,
+    isConnected: !!currentAccount,
+    address: currentAccount?.address,
+    signAndExecute,
+  };
+}