A headless CMS for Supabase Storage. Built with Next.js 14, TypeScript, and Tailwind CSS.

🚀 Quick Start with Template

1. Create a new project

   npx create-supawald my-app
   cd my-app

2. Set up your Supabase project

   • Create a new bucket in Supabase Storage
   • Get your project URL and anon key from Settings -> API
   • Copy .env.example to .env.local and fill in your credentials:

     NEXT_PUBLIC_SUPABASE_URL=your-project-urlNEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-keyNEXT_PUBLIC_BUCKET_NAME=your-bucket-nameAUTH_USERNAME=adminAUTH_PASSWORD=your-secure-password

3. Start the development server

   npm install
   npm run dev

4. Visit http://localhost:3000 and log in with your credentials

Note: The template includes a complete Next.js application with file management, authentication, and static site generation support.

Supawald

A headless CMS for Supabase Storage. Built with Next.js 14, TypeScript, and Tailwind CSS. Provides a clean interface for managing files in Supabase Storage buckets with real-time updates and static site generation support.

What is Supawald?

Supawald is a file management system that turns Supabase Storage into a full-featured CMS. It's designed for developers who need a simple way to manage assets for their Next.js applications, blogs, or any project using Supabase Storage.

Key Features

• File Management

  • Drag & drop file uploads
  • Folder navigation
  • File deletion
  • In-place file editing
  • Real-time updates via Supabase subscriptions

• Developer Experience

  • TypeScript for type safety
  • Next.js 14 App Router
  • Tailwind CSS for styling
  • Basic auth protection
  • Publish API for static site generation

• Storage Features

  • Public/private bucket support
  • File type detection
  • File size tracking
  • Last modified timestamps

Use Cases

1. Blog Asset Management

   • Store and manage images, documents, and other media
   • Organize content by date, category, or project
   • Quick access to frequently used assets

2. Document Management

   • Store and organize PDFs, spreadsheets, and other documents
   • Version control through Supabase's built-in features
   • Secure access control via bucket policies

3. Application Assets

   • Manage static assets for web applications
   • Store user uploads and generated content
   • Handle media files for user profiles or content

Technical Requirements

• Node.js 18+
• Supabase account (free tier works)
• npm or yarn

▶️ Quick Start

Use the CLI

npx create-supawald my-app
cd my-app
npm install
npm run dev

Or clone manually

git clone https://github.com/yourusername/supawald.git
cd supawald/template
npm install
npm run dev

2. Set Up Supabase

   -- Create a new bucket in Supabase Storage-- Name it something like 'blog-content' or 'assets'-- Set appropriate privacy settings (public/private)

3. Configure Environment

   cp .env.example .env.local

   # SupabaseNEXT_PUBLIC_SUPABASE_URL=your-project-urlNEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-keyNEXT_PUBLIC_BUCKET_NAME=your-bucket-name# Auth (for admin access)AUTH_USERNAME=adminAUTH_PASSWORD=your-secure-password# Publish API (for static site generation)PUBLISH_URL=https://your-site.com/api/publishPUBLISH_TOKEN=your-secure-token

4. Run Development Server

   npm run dev

Static Site Generation Integration

Supawald includes a publish API that triggers regeneration of static pages that depend on Supabase Storage data. This is useful for:

• Blog posts that display uploaded images
• Product pages with product images
• Any static page that needs to reflect changes in your storage bucket

Setting Up Your Static Site

1. Create a Publish API Route Create a new API route in your Next.js application at pages/api/publish.ts:

   import{NextApiRequest,NextApiResponse}from'next'exportdefaultasyncfunctionhandler(req: NextApiRequest,res: NextApiResponse){// Check for secret to confirm this is a valid requestif(req.headers.authorization!==`Bearer ${process.env.PUBLISH_TOKEN}`){returnres.status(401).json({message: 'Invalid token'})}try{// Revalidate your static pagesawaitres.revalidate('/')// Revalidate homepageawaitres.revalidate('/blog')// Revalidate blog pagesawaitres.revalidate('/products')// Revalidate product pagesreturnres.json({revalidated: true})}catch(err){// If there was an error, Next.js will continue// to show the last successfully generated pagereturnres.status(500).send('Error revalidating')}}

2. Configure Environment Variables In your Supawald instance:

   PUBLISH_URL=https://your-static-site.com/api/publishPUBLISH_TOKEN=your-secure-token

   In your static site:

   PUBLISH_TOKEN=your-secure-token# Same token as above

3. Using the Publish Button When you click the publish button in Supawald:

   • It sends a POST request to your static site's publish API
   • Your static site regenerates the specified pages
   • The new content becomes available on your static site

Example Usage

// In your static site's page componentexportasyncfunctiongetStaticProps(){// Fetch data from Supabase Storageconst{data: images}=awaitsupabase.storage.from('your-bucket').list('blog-images')return{props: {
images,// ... other props},// Revalidate every hourrevalidate: 3600}}

When you update an image in Supawald and click publish:

1. The image is updated in Supabase Storage
2. The publish API is called
3. Your static pages are regenerated with the new image
4. The changes are live on your static site

API Integration

File Operations

// Example: Upload a fileconst{ data, error }=awaitsupabase.storage.from('your-bucket').upload('path/to/file.jpg',file)// Example: Get file URLconst{data: { publicUrl }}=supabase.storage.from('your-bucket').getPublicUrl('path/to/file.jpg')

Static Site Generation

// Trigger static page regenerationawaitfetch('/api/publish',{method: 'POST',headers: {'Authorization': `Bearer ${process.env.PUBLISH_TOKEN}`}})

🔒 Security Best Practices

1. Supabase Storage

   • Use private buckets for sensitive content
   • Implement RLS policies for bucket access
   • Set up CORS rules for your domain
   • Use signed URLs for temporary access

2. Authentication

   • Use strong passwords for admin access
   • Implement rate limiting
   • Set up proper CORS headers
   • Use HTTPS in production

3. Environment Variables

   • Never commit .env.local
   • Rotate credentials regularly
   • Use different keys for development/production
   • Consider using a secrets manager
   • Keep your PUBLISH_TOKEN secure and only share with trusted services

Development

# Install dependencies
npm install
# Run development server
npm run dev
# Build for production
npm run build
# Start production server
npm start

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

Apache 2.0 - See LICENSE for details.

🎉 Join the Community

• GitHub Issues: Found a bug? Let us know here.
• Community Forum: Reach out here
• Discussions: Share your ideas and ask questions in our discussion forum.

📢 Stay Connected