Svelte + NeutralinoJS + Tailwind Template

A modern desktop application template combining the best of web technologies with native desktop capabilities. This template embeds a SvelteKit development server within a NeutralinoJS client window, providing hot-reload during development and native API access.

Features

• ⚡ Svelte 5 - Latest Svelte with runes for reactive state management
• 🖥️ NeutralinoJS - Lightweight native desktop framework (no Chromium bundling)
• 🎨 Tailwind CSS 4 - Utility-first CSS framework
• 🔥 Hot Reload - Full HMR support during development
• 🛠️ TypeScript - Full type safety
• 📦 Deno Task Runner - Modern JavaScript runtime for task orchestration
• 🔧 Native API Access - OS integration, file system, notifications, and more
• 🌐 Cross-Platform - Windows, macOS, and Linux support

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Desktop Window                            │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              NeutralinoJS Container                    │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │           SvelteKit Dev Server                   │  │  │
│  │  │         (http://localhost:5173)                  │  │  │
│  │  │                                                   │  │  │
│  │  │  ┌─────────────────────────────────────────────┐ │  │  │
│  │  │  │         Svelte Application                   │ │  │  │
│  │  │  │  • Hot Module Replacement (HMR)              │ │  │  │
│  │  │  │  • Native API Integration                    │ │  │  │
│  │  │  │  • Tailwind Styling                          │ │  │  │
│  │  │  └─────────────────────────────────────────────┘ │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Project Structure

.
├── deno.json                    # Deno task runner configuration
├── scripts/
│   ├── setup.sh                 # Unix setup script
│   └── setup.bat                # Windows setup script
├── src/
│   ├── client/                  # NeutralinoJS client
│   │   ├── neutralino.config.json
│   │   └── .gitignore
│   └── server/                  # SvelteKit application
│       ├── package.json
│       ├── svelte.config.js
│       ├── vite.config.ts
│       ├── tsconfig.json
│       └── src/
│           ├── app.html
│           ├── app.d.ts
│           ├── lib/
│           │   ├── index.ts
│           │   ├── neutralino.ts    # Neutralino integration
│           │   └── assets/
│           └── routes/
│               ├── +layout.svelte
│               ├── +page.svelte
│               └── layout.css

Quick Start

Prerequisites

• Node.js 18+ (Download)
• Deno 1.40+ (Download)
• Neutralino CLI (install globally):

  npm install -g @neutralinojs/neu
  

Setup

1. Install npm dependencies:

   deno task install
   

2. Generate SvelteKit types and sync configuration:

   deno task prepare
   

   Note: This generates the .svelte-kit/tsconfig.json file that the project extends. Run this whenever you add new dependencies or change SvelteKit configuration.

3. Download Neutralino binaries:

   cd src/client && neu update
   

Running the Project

Option 1: Run both server and client (Recommended)

deno task dev:neutralino

This starts both the SvelteKit dev server and the Neutralino client simultaneously.

Option 2: Run separately (for debugging)

Terminal 1 - Start SvelteKit dev server:

deno task dev:server

Terminal 2 - Start Neutralino client:

deno task dev:client

Option 3: Run SvelteKit only (browser development)

deno task dev

Open http://localhost:5173 in your browser.

Troubleshooting

Type errors about missing type definitions

If you see errors like Cannot find type definition file for 'node' or Cannot find module '@sveltejs/kit':

1. Make sure you've run deno task install to install npm dependencies
2. Run deno task prepare to generate SvelteKit types
3. Restart your editor's TypeScript language server

Error: Cannot find module '.svelte-kit/tsconfig.json'

Run deno task prepare to generate the SvelteKit configuration files.

Neutralino client shows blank screen

Make sure the SvelteKit dev server is running on port 5173 before starting the Neutralino client.

Available Tasks

Development

Building

Quality

Development Workflow

Hot Reload Development

The template supports full hot module replacement (HMR):

1. Changes to Svelte components update instantly in the Neutralino window
2. Tailwind CSS changes are reflected immediately
3. Native API calls work seamlessly during development

Native API Integration

Use the $lib/neutralino module to access native capabilities:

<script lang="ts">
  import { isNeutralino, showNotification, selectFile, closeApp } from '$lib/neutralino';

  async function handleNotify() {
    await showNotification('Hello', 'From Svelte!');
  }

  async function handleOpenFile() {
    const files = await selectFile({
      filters: [{ name: 'Images', extensions: ['png', 'jpg', 'gif'] }]
    });
    console.log('Selected:', files);
  }
</script>

<button onclick={handleNotify} disabled={!isNeutralino()}>
  Show Notification
</button>

Available Native APIs

• App: closeApp(), restartApp()
• OS: showNotification(), showMessageBox(), selectFile(), saveFile()
• Filesystem: readTextFile(), writeTextFile(), createDirectory()
• Storage: setStorageItem(), getStorageItem()
• System: getSystemInfo()

Configuration

SvelteKit (src/server/svelte.config.js)

The template uses @sveltejs/adapter-static to build for Neutralino:

adapter: adapter({
  pages: '../client/resources',
  assets: '../client/resources',
  fallback: 'index.html'
})

Neutralino (src/client/neutralino.config.json)

Key settings for development:

{
  "url": "/",
  "enableNativeAPI": true,
  "nativeAllowList": [
    "app.*",
    "os.*",
    "filesystem.*",
    "storage.*",
    "computer.*"
  ]
}

Vite (src/server/vite.config.ts)

Configured for cross-origin requests from Neutralino:

server: {
  host: true,
  cors: { origin: '*' }
}

Production Build

To create a production release:

# Build everything
deno task build:neutralino

# Output location
src/client/dist/

The production build:

1. Compiles SvelteKit to static files in src/client/resources/
2. Bundles Neutralino binaries for your platform
3. Creates distributable packages in src/client/dist/

Cross-Platform Considerations

File Paths

Use Neutralino's filesystem API for cross-platform path handling:

import { readTextFile, writeTextFile } from '$lib/neutralino';

// Works on all platforms
const content = await readTextFile('./data/config.json');

Platform Detection

import { getSystemInfo } from '$lib/neutralino';

const info = await getSystemInfo();
console.log(info.os.name); // 'Windows', 'Darwin', 'Linux'

Troubleshooting

TypeScript Errors

If you see Cannot find module errors:

deno task prepare  # Generate SvelteKit types
deno task install  # Reinstall dependencies

Neutralino Not Detected

Ensure you're running the app through Neutralino:

# Don't just open in browser
deno task dev  # Only starts SvelteKit

# Use instead:
deno task dev:neutralino  # Starts both

Hot Reload Not Working

1. Check that port 5173 is available
2. Ensure host: true is set in vite.config.ts
3. Verify firewall settings for local connections

Technologies

• Svelte 5 - Cybernetically enhanced web apps
• SvelteKit - The official Svelte application framework
• NeutralinoJS - Portable and lightweight cross-platform desktop application development framework
• Tailwind CSS 4 - A utility-first CSS framework
• Deno - A modern runtime for JavaScript and TypeScript
• Vite - Next generation frontend tooling

License

MIT - See LICENSE for details.

Contributing

Contributions welcome! Please follow the existing code style and ensure:

1. TypeScript strict mode compliance
2. Cross-platform compatibility
3. Proper error handling for native API calls