Svelte Headless UI Starter

Launch your next Svelte app using Headless UI.

Template designed to make it faster and easier to build libre Svelte apps using Headless UI.

Demo

View the online demo to see what you can expect.

Highlights

• 🏗️ SvelteKit cybernetically enhanced routing
• 🔨 Svelte for developing fast, lightweight apps
• 🎨 Tailwind CSS with Forms and Typography plugins
• 🧪 Headless UI for a sophisticated, accessible UI
• 💄 Prettier with Tailwind automatic class sorting
• 🚩 Unplugin Icons to access to all Icônes icons
• ⚡️ Cssnano for production stylesheet compression
• ⚡️ Service Worker dynamic resource caching
• ✏️ Fontsource self-hosted web font integration
• 🎭 Playwright browser testing framework
• 🦋 Changesets to manage versioning and changelogs
• 📈 Basic SEO with large social sharing cards
• 🚀 Vercel deployments functional out of the box
• 🔐 OAuth via GitHub, extendible to other providers
• ⚗️ Supabase integration utilizing GraphQL
• 🦄 GraphQL language server via remote schema
• 👷 Gravitar support for non-logged in users
• 📄 AGPL-licensed free (as in freedom) software

Structure

The application structure is as follows:

├── src
│   ├── db
│   ├── environment
│   ├── hooks
│   ├── lib
│   │   ├── core
│   │   │   └── services
│   │   │       ├── auth
│   │   │       ├── graphql
│   │   │       ├── http
│   │   │       └── supabase
│   │   ├── data
│   │   ├── graphql
│   │   ├── models
│   │   │   ├── classes
│   │   │   ├── interfaces
│   │   │   └── types
│   │   ├── shared
│   │   │   ├── components
│   │   │   │   ├── auth
│   │   │   │   ├── calendar
│   │   │   │   ├── form
│   │   │   │   ├── meta
│   │   │   │   └── navigation
│   │   │   └── layouts
│   │   └── utils
│   └── routes
│       ├── account
│       └── api
│           ├── auth
│           └── user
├── static
└── tests

Setup

Copy .env.example to .env before running the app. The app will run using the defaults provided, however, OAuth configuration is required to access protected routes and Supabase is required for dynamic behaviors such as adding events to the included Calendar component.

OAuth

To configure authentication using GitHub as an OAuth provider create an OAuth app as described in Creating an OAuth App then fill out the GITHUB_ prefixed items in your .env file with those provided by GitHub. OAuth is enabled during development by default although it will not function without an active provider.

Supabase

To use Supabase create a new project on the Supabase website then fill out the SUPABASE_ prefixed items in your .env file with those provided by Supabase. Afterwards run src/db/setup.sql from within the Supabase online SQL Editor to configure and seed your database. Supabase is disabled during development by default.

GraphQL

Supabase can be used with REST and GraphQL via the pg_graphql extension which is enabled by default for projects created after Mar 28, 2022. This starter utilizes a simple GraphQL client to access some Supabase data and, as a result, requires pg_graphql to be enabled in order to function when Supabase is used. The setup.sql file contains the necessary configuration for GraphQL and no additional steps are required.

Visit Activate and Use Supabase GraphQL to understand how it works.

GraphQL language server features such as query completions will begin to function automatically once the .env file is configured. See .graphqlrc.yml for setup. Using this approach you do not need to duplicate server schema in your app. Assumes you're using an editor plug-in which understands how to read graphql-config.

Developing

Once you've completed setup and installed dependencies with pnpm install, start a development server:

pnpm run dev

# or start the server and open the app in a new browser tab
pnpm run dev -- --open

By default development builds will not utilize Supabase. This behavior can be controlled using the debug flag in environment.dev.ts. If you have already setup Supabase, set the debug flag to false to develop using live data.

Making commits

Use the approach that best suits your personal preferences and preferred work style. If you would like to add emojis to your commit messages, see Emojify Conventional Commits with Git for one approach.

Adding a changeset

To add a changeset run pnpm changeset and follow the prompts. If this is your first time adding a changeset, run pnpm changeset init to create the .changeset folder and commit it to the repository.

Building

To create a production version of your app:

pnpm run build

You can preview the production build with npm run preview.

By default production builds will utilize Supabase. This behavior can be controlled using the debug flag in environment.prod.ts. If you have not yet setup Supabase or do not wish to use it, set the debug flag to true to deploy using mock data.

Versioning

To create a new version run pnpm changeset version and follow the prompts.

Publishing

To publish a new version run pnpm changeset publish to generate a CHANGELOG, followed by git push --follow-tags. Assumes you have logged into NPM and have a git remote configured.

Deploying

Supported deployment environments include Vercel, Cloudflare and Netlify. Other environments may be supported in the future. See adapter-auto for list of automatically supported environments.

Note that although Cloudflare uses Node to build the project its SSR functionality is performed in Web Workers. As a result, code that requires Node explicitly such as dotenv is forbidden. Reference the engines property in package.json for the minimum Node version required to build the project regardless of deployment target used.

Vercel

To deploy your app to Vercel run vercel for testing or vercel --prod for production. Assumes you've signed-up for and authenticated with Vercel from the Vercel CLI. No additional configuration is required. If you wish to create a Continuous Integration (CI) setup with a git repo connected to Vercel, consult the Vercel docs.

Cloudflare Pages

You can get a CI setup running without any additional configuration as described in the Cloudflare Docs for Svelte. See Wrangler Configuration and here for CLI-based deployments, which are a bit more involved.

Error 1102: Worker exceeded resource limits

Once you've deployed to Cloudflare Pages, if you see the error indicated that means you've gone over the CPU budget during server-side rendering. Cloudflare set a 50ms budget for Functions (Workers) during the beta. Enable the debug flag in environment.prod.ts and try again.

Rights

Svelte Headless UI Starter - Launch your next Svelte app using Headless UI.
Copyright (C) 2022  VHS <[e-mail]> (https://vhs.codeberg.page)

Svelte Headless UI Starter is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.