Getting Started

In this tutorial, you'll create your first live wallpaper with Fluxlay and preview it on your desktop.

⚡ Want to skip the boilerplate? Use the official Claude Code plugin — describe what you want and Claude scaffolds, implements, and ships it from a single prompt.

Prerequisites

Node.js v18 or later
A package manager of your choice (npm / pnpm / yarn / bun)
Fluxlay desktop app installed

Create a Project

Create a new directory and initialize the project:

mkdir my-wallpaper && cd my-wallpaper

pnpm init

Install the required dependencies:

pnpm add react react-dom @fluxlay/react

pnpm add -D @fluxlay/cli @fluxlay/vite @vitejs/plugin-react vite

Configure the Manifest

Create a fluxlay.yaml in the project root:

fluxlay.yaml

schemaVersion: 1
name: My First Wallpaper
slug: my-first-wallpaper
version: 0.1.0
kind: web
description: My first Fluxlay wallpaper.

Configure Vite

Create a vite.config.ts:

vite.config.ts

import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import { fluxlay } from "@fluxlay/vite";
 
export default defineConfig({
  plugins: [react(), fluxlay()]
});

Create the Entry Point

Create index.html:

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Create src/main.tsx:

src/main.tsx

import { StrictMode, useEffect, useState } from "react";
import { createRoot } from "react-dom/client";
 
function Wallpaper() {
  const [count, setCount] = useState(0);
 
  useEffect(() => {
    const id = setInterval(() => setCount(c => c + 1), 1000);
    return () => clearInterval(id);
  }, []);
 
  return (
    <main
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        height: "100vh",
        width: "100vw",
        backgroundColor: "#1a1a2e",
        color: "#e0e0e0",
        fontSize: "2rem",
        fontFamily: "sans-serif"
      }}
    >
      Hello, Fluxlay! ({count}s)
    </main>
  );
}
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Wallpaper />
  </StrictMode>
);

Preview on Your Desktop

Start the development server:

pnpm fluxlay dev

The Fluxlay desktop app will detect the dev server and display your wallpaper with hot reload. Every time you save a file, the wallpaper updates instantly.

Next Steps

Pick whichever topic interests you next. The two tutorials below are independent — take them in either order, or skip one entirely.

Interactive Wallpaper — Use SDK hooks to make your wallpaper respond to mouse movement.
Shell Wallpaper — Display live system information with shell commands.

💡 Tip: Planning to pull data from an external API? See Fetch External APIs (CORS workaround) — it covers network: declarations and when to use proxiedFetch for endpoints that don't return CORS headers.

Want a head start? Browse the official example wallpapers on GitHub — each one is a full project you can clone, run, and remix.

When you're ready to ship, head to Publish Your Wallpaper.