Shogun Ripple Boilerplate

A complete Ripple application template with Shogun Core integration, featuring real-time data synchronization, user authentication, and modern UI components.

🚀 Features

• Ripple Framework: Modern reactive UI framework with TypeScript support
• Shogun Core Integration: Real-time data synchronization with GunDB
• User Authentication: Complete auth system with session persistence
• DaisyUI Components: Beautiful, accessible UI components
• Dark/Light Mode: Toggle between themes with persistence
• Real-time Counter: Demonstrates live data synchronization
• Modern Tooling: Vite, Prettier, and TypeScript configured

📋 Prerequisites

• Node.js >= 20.0.0
• npm, yarn, or pnpm

🛠️ Getting Started

1. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

2. Start Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

The application will be available at http://localhost:3000

3. Build for Production

npm run build
# or
yarn build
# or
pnpm build

4. Preview Production Build

npm run serve
# or
yarn serve
# or
pnpm serve

🏗️ Project Structure

src/
├── hooks/                    # Custom Ripple hooks
│   ├── useGunAuth.ripple     # Authentication hook
│   ├── useGunData.ripple     # Data management hook
│   ├── useGunInstance.ripple # GunDB instance hook
│   └── useSessionPersistence.ripple # Session management
├── App.ripple               # Main application component
├── index.ts                 # Application entry point
└── app.css                  # Global styles

🔧 Configuration

Shogun Core Settings

The application connects to multiple GunDB peers for redundancy:

const shogun = useGunInstance({
    peers: [
        'https://relay.shogun-eco.xyz/gun',
        'https://peer.wallie.io/gun',
        'https://v5g5jseqhgkp43lppgregcfbvi.srv.us/gun'
    ],
    appScope: 'shogun-ripple-boilerplate'
});

DaisyUI Theme Configuration

The app supports light and dark themes with automatic system preference detection:

// Theme initialization
effect(() => {
    const savedTheme = localStorage.getItem('theme');
    const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    const initialTheme = savedTheme || systemTheme;
    
    @currentTheme = initialTheme;
    document.documentElement.setAttribute('data-theme', initialTheme);
});

🎣 Custom Hooks

useGunAuth

Handles user authentication with session persistence:

const { user, isLoggedIn, login, signup, logout, loading } = useGunAuth(shogun);

Features:

• Automatic session restoration
• Login/signup with validation
• Real-time auth state updates
• Error handling

useGunData

Manages real-time data synchronization:

const { data, loading, error, put, get, remove, set } = useGunData(shogun, 'path', defaultValue);

Features:

• Real-time data updates
• CRUD operations (put, get, remove, set)
• Loading and error states
• Automatic reconnection

useGunInstance

Creates and manages GunDB instances:

const shogun = useGunInstance({
    peers: ['peer1', 'peer2'],
    appScope: 'my-app'
});

Features:

• Singleton pattern for global instance
• Multiple peer connections
• Application scoping
• Auto-initialization

useSessionPersistence

Manages session restoration and monitoring:

const { isSessionRestored, sessionError, retrySessionRestore } = useSessionPersistence(shogun);

Features:

• Session status monitoring
• Automatic retry logic
• Error reporting
• Session validation

🎨 UI Components

Counter Component

The demo counter showcases real-time data synchronization:

// Counter operations
const incrementCounter = async () => {
    if (@isLoggedIn) {
        const currentValue = @counterData?.value || 0;
        const newValue = currentValue + 1;
        await putCounterData({ 
            value: newValue, 
            lastUpdated: new Date().toISOString() 
        });
    }
};

Authentication Forms

Built with DaisyUI form components:

<div class='form-control w-full'>
    <label class='label'>
        <span class='label-text'>Username</span>
    </label>
    <input 
        type='text' 
        placeholder='Enter your username'
        value={@authUsername}
        onInput={(e) => @authUsername = e.target.value}
        class='input input-bordered w-full'
    />
</div>

🎭 Theme System

Toggle Theme Function

const toggleTheme = () => {
    const newTheme = @currentTheme === 'light' ? 'dark' : 'light';
    @currentTheme = newTheme;
    
    // Apply theme to document
    document.documentElement.setAttribute('data-theme', newTheme);
    
    // Save preference
    localStorage.setItem('theme', newTheme);
};

Theme Button Component

<button onClick={toggleTheme} class='btn btn-ghost btn-circle'>
    {#if @currentTheme === 'light'}
        <svg><!-- Moon icon --></svg>
    {:else}
        <svg><!-- Sun icon --></svg>
    {/if}
</button>

📝 Code Formatting

This template includes Prettier with the Ripple plugin for consistent code formatting.

Available Commands

• npm run format - Format all files
• npm run format:check - Check if files are formatted correctly

Configuration

Prettier is configured in .prettierrc:

{
    "useTabs": true,
    "singleQuote": true,
    "trailingComma": "es5",
    "printWidth": 100,
    "tabWidth": 4,
    "plugins": ["prettier-plugin-ripple"]
}

VS Code Integration

For the best development experience, install:

• Prettier VS Code extension
• Ripple VS Code extension

🔐 Authentication Flow

1. User Registration/Login: Users can sign up or log in with username/password
2. Session Persistence: Sessions are automatically restored on page refresh
3. Real-time Auth State: Authentication state updates in real-time across components
4. Secure Logout: Clean session termination with state reset

📊 Data Synchronization

The boilerplate demonstrates real-time data synchronization:

1. User Space: Data is stored in the user's personal space
2. Real-time Updates: Changes sync instantly across all connected clients
3. Offline Support: Data persists and syncs when connection is restored
4. Conflict Resolution: GunDB handles data conflicts automatically

🚀 Deployment

Build Process

# Create production build
npm run build

# Preview build locally
npm run serve

Environment Configuration

The app connects to public GunDB peers by default. For production, consider:

1. Setting up your own GunDB relay
2. Configuring custom peers
3. Implementing additional security measures

🛡️ Security Considerations

• Client-side Authentication: Auth is handled client-side with GunDB
• Data Encryption: GunDB provides end-to-end encryption
• Peer Selection: Use trusted peers for production deployments
• Session Management: Sessions are tied to browser storage

📚 Learn More

• Ripple Documentation - Ripple framework docs
• Vite Documentation - Build tool documentation
• DaisyUI Documentation - UI component library
• GunDB Documentation - Database documentation
• Shogun Core - Core integration library

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Join our community discussions

---

Happy coding with Shogun Ripple Boilerplate! 🎉