celestite Svelte Themes

Celestite

Beautifully reactive, server-side rendered Svelte apps w/ a Crystal backend

#crystal#framework#web#ssr#amber#amber-framework#universal#isomorphic#svelte#sapper
Download

celestite

Crystal + Svelte = :zap:

Celestite allows you to use the full power of Svelte reactive components in your Crystal web apps. It's a drop-in replacement for your view layer -- no more need for intermediate .ecr templates. With celestite, you write your backend server code in Crystal, your frontend client code in JavaScript & HTML, and everything works together seamlessly...and fast.

Introduction

Read the full introductory blog post here.

Requirements

  • Crystal 1.0.0+
  • Bun 1.0+ (for the SSR render server)

Installation

THIS IS PREVIEW / EARLY ALPHA SOFTWARE

This is not much more than a proof-of-concept at the moment, but it does work! Standard warnings apply - it will likely break/crash in spectacular and ill-timed glory, so don't poke it, feed it past midnight, or use it for anything mission-critical (yet).

Celestite has been developed / tested with Kemal, but there's no reason it won't work with Amber, Lucky, Athena, etc. (but no work integrating with those has been done yet.) The steps below assume you'll be working with Kemal.

1. Add celestite to your application's shard.yml and run shards install

dependencies:
  celestite:
    github: noahlh/celestite
    version: ~> 0.2.0

The postinstall hook will automatically install JavaScript dependencies via Bun.

2. Include the helper:

For Kemal:

require "celestite"
include Celestite::Adapter::Kemal

3. Add initialization code

Create an initializer file (e.g., /config/initializers/celestite.cr):

require "celestite"

Celestite.initialize(
  engine: Celestite::Engine::Svelte,
  component_dir: "#{Dir.current}/src/views/",
  build_dir: "#{Dir.current}/public/celestite/",
  port: 4000,
  vite_port: 5173,
)

See example config for more options.

4. Add a static route for your build_dir

For Kemal:

# myapp.cr

add_handler Kemal::StaticFileHandler.new("./public/celestite")

5. Add your .svelte files and start building!

Name your root component index.svelte (all lowercase).

Usage

celestite_render

celestite_render(component : String?, context : Celestite::Context?, layout : String?)

Call this where you'd normally call render in your controllers.

  • component - The Svelte component to render (without .svelte extension)
  • context - A Celestite::Context hash with data to pass to your component
  • layout - Optional HTML layout file from your layout_dir

Example

<!-- src/views/layouts/layout.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- CELESTITE HEAD -->
    <!-- The above comment is actually needed - Celestite looks for it and injects optional svelte:head content -->
  </head>
  <body>
    <div id="celestite-app">
      <!-- CELESTITE BODY -->
      <!-- The above comment is also actually needed - Celestite looks for it and injects the server-side rendered component -->
    </div>
    <!-- CELESTITE CLIENT -->
    <!-- The above comment is also also actually needed - Celestite looks for it and injects the client-side bundle -->
  </body>
</html>

# myapp.cr
get "/test" do
  context = Celestite::Context{ data: "Hello from Crystal!" }
  celestite_render(component:"Home.svelte", context: context, layout: "layout.html")
end

Accessing Context in Svelte

<script>
  let { context } = $props();
</script>

<h1>Result: {context.data}</h1>

Server vs Client Rendering

Your .svelte components are automatically rendered server-side before being sent to the client, then hydrated on the client for interactivity.

Code that relies on browser-specific APIs (like document or window) must be wrapped in Svelte's onMount() or otherwise guarded.

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    // Browser-only code here
    console.log(window.location);
  });
</script>

or

<script>
  let isBrowser = false;

  if (typeof window !== 'undefined') {
    isBrowser = true;
  }
</script>

{#if isBrowser}
  <!-- Browser-specific content -->
{/if}

HTTPS/SSL Support for Development

Celestite supports running the Vite dev server over HTTPS, useful for tunneled connections (ngrok, localtunnel, etc.).

Setup

  1. Install mkcert:

    brew install mkcert  # macOS

  2. Install the local CA:

    sudo mkcert -install

  3. Generate certificates:

    mkcert -key-file dev.key -cert-file dev.crt localhost 127.0.0.1 ::1

  4. Enable in configuration:

    Celestite.initialize(
  dev_secure: true,
  # ... other config
)

Production Builds

For production, Svelte components must be pre-built using Vite.

Building

From your app's root directory:

# Build client bundles
COMPONENT_DIR=/path/to/views BUILD_DIR=/path/to/public/celestite \
  bunx --bun vite build --config /path/to/lib/celestite/vite.config.js

# Build SSR bundles
COMPONENT_DIR=/path/to/views BUILD_DIR=/path/to/public/celestite \
  bunx --bun vite build --config /path/to/lib/celestite/vite.config.js --ssr

Or use the Makefile target:

cd /path/to/lib/celestite/src/svelte-scripts
make build COMPONENT_DIR=/path/to/views BUILD_DIR=/path/to/public/celestite

Build Output

  • BUILD_DIR/client/ - Client-side JS/CSS with content hashes
  • BUILD_DIR/client/.vite/manifest.json - Asset manifest for hydration
  • BUILD_DIR/server/ - SSR modules for server-side rendering

Testing Production Builds Locally

NODE_ENV=production NODE_PORT=4000 \
  COMPONENT_DIR=/path/to/views \
  LAYOUT_DIR=/path/to/views/layouts \
  BUILD_DIR=/path/to/public/celestite \
  bun run /path/to/lib/celestite/src/svelte-scripts/vite-render-server.js

Configuration Options

Option Default Description
engine Svelte Rendering engine (currently only Svelte)
component_dir - Path to your Svelte components
layout_dir - Path to HTML layout templates
build_dir - Output directory for production builds
port 4000 Bun SSR server port
vite_port 5173 Vite dev server port (development only)
dev_secure false Enable HTTPS for dev server
disable_a11y_warnings false Suppress Svelte accessibility warnings

Roadmap

  • Svelte 5 support with Vite
  • Hot Module Reloading (HMR)
  • Production builds with content hashing
  • Example/demo project

Contributing

Contributions are welcome! This is an open source project and feedback, bug reports, and PRs are appreciated.

  1. Fork it (https://github.com/noahlh/celestite/fork)
  2. Create your feature branch (git checkout -b my-feature)
  3. Write tests!
  4. Commit your changes (git commit -am 'Add feature')
  5. Push to the branch (git push origin my-feature)
  6. Create a Pull Request

Contributors

Top categories

tailwinddaisyuiadmin templatepopupmdsvexportfolioblogformecommerceuicarouselauthdarkseoimagerouting
Loading Svelte Themes