Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/remotes/CHANGELOG.md
• packages/remotes/eslint.config.js
• packages/remotes/package.json
• packages/remotes/src/lib/enhance.svelte.ts
• packages/remotes/src/lib/index.ts
• packages/remotes/src/lib/validation.svelte.ts
• packages/remotes/svelte.config.js
• packages/remotes/tsconfig.json
• packages/remotes/vite.config.ts

The @opensky/remotes package provides helper utilities to improve the developer and user experience when working with SvelteKit's remote form functions. It offers two main exports, createValidation and createEnhancedForm, which add enhanced validation logic and form state management, respectively.

This guide covers the necessary prerequisites, installation process, and basic configuration required to integrate @opensky/remotes into a SvelteKit project. The setup involves installing the package, ensuring peer dependencies are met, and then importing and initializing the helper functions within your Svelte components.

Sources: README.md:3-4, packages/remotes/src/lib/index.ts

Prerequisites

Before installing @opensky/remotes, ensure your project meets the following peer dependency requirements. The package is designed to work within a modern SvelteKit environment.

Dependency	Required Version	Description
@sveltejs/kit	^2.27.0	The SvelteKit framework.
svelte	^5.0.0	The Svelte compiler and runtime.

The package also has a direct dependency on runed for its useDebounce utility.

Dependency	Required Version	Description
runed	^0.35.1	Provides reactive primitives and utilities.

Sources: packages/remotes/package.json:15-21

The following diagram illustrates the package's primary dependencies.

Installation

Install the package into your SvelteKit project using your preferred package manager.

npm install @opensky/remotes

Sources: packages/remotes/package.json:3

Project Configuration

The @opensky/remotes package is designed to integrate seamlessly into a standard SvelteKit project that uses Vite and TypeScript. The package itself is configured with the following tools, which reflects the expected environment of a consumer.

File	Description
vite.config.ts	Configures the Vite build tool using the SvelteKit plugin (@sveltejs/kit/vite).
svelte.config.js	Standard SvelteKit configuration, using vitePreprocess() and an adapter like @sveltejs/adapter-auto.
tsconfig.json	TypeScript configuration that extends the base SvelteKit tsconfig.json and enables strict type checking.
eslint.config.js	ESLint configuration for linting TypeScript and Svelte files.

No special configuration is required to use the package, provided your project follows a standard SvelteKit setup.

Sources: packages/remotes/vite.config.ts, packages/remotes/svelte.config.js, packages/remotes/tsconfig.json, packages/remotes/eslint.config.js

Basic Usage & Integration

The core setup involves importing and initializing the createValidation and createEnhancedForm helpers in your Svelte component script.

The overall setup flow is as follows:

1. Install the package.
2. Import helpers from @opensky/remotes.
3. Define a remote form using SvelteKit's createRemote.
4. Instantiate createValidation with the remote form.
5. Instantiate createEnhancedForm, passing it the remote form and the validation instance.
6. Apply the form enhancement and validation handlers to the HTML form and its input fields.

This diagram shows the setup flow within a Svelte component.

Step 1: Import Helpers

Import the necessary functions from the package in your Svelte component.

import { createValidation, createEnhancedForm } from '@opensky/remotes';
import { myForm } from './myForm.remote'; // Your SvelteKit remote form
import { z } from 'zod'; // Assuming Zod for schema validation

Sources: README.md:121-124, packages/remotes/src/lib/index.ts:1-2

Step 2: Initialize Helpers

Create instances of the validation and form helpers. createValidation takes the remote form as an argument. createEnhancedForm takes the remote form and an options object, where you can pass the validation instance for automatic integration.

// Define a schema for validation
const schema = z.object({
  name: z.string().min(4, 'Too short').max(10, 'Too long'),
  address: z.object({
    state: z.string()
  })
});

// Initialize the helpers
const valid = createValidation(myForm);
const form = createEnhancedForm(myForm, {
  validation: valid,
  delayMs: 500,
  timeoutMs: 3500
});

Sources: README.md:126-138, packages/remotes/src/lib/validation.svelte.ts:15, packages/remotes/src/lib/enhance.svelte.ts:221

Step 3: Apply to Svelte Markup

Connect the helpers to your form and input elements.

• Use the spread operator ... to apply preflight and enhance from the remote form and the enhanced form helper.
• Use the spread operator ... to apply onblur and oninput handlers from the validation helper to each field.
• Use the issues() method from the validation helper to conditionally apply styles or display error messages.

<script lang="ts">
  // ... (imports and initialization from previous steps)
</script>

<p>State: {form.state}</p>

<form {...myForm.preflight(schema).enhance(opts =>
  form.enhance(opts, {
    onDelay: () => console.log('showing loader'),
    onTimeout: () => console.log('request timeout'),
    onReturn: ({ result }) => console.log('success', result)
  })
)}>
  <input
    {...myForm.fields.name.as('text')}
    {...valid.fields('name')}
    class:error={valid.issues('name')}
  />

  {#if valid.issues('name')}
    {#each valid.issues('name') as issue}
      <p class="error">{issue}</p>
    {/each}
  {/if}

  <button disabled={form.pending || form.delayed}>
    {form.delayed ? 'Loading...' : 'Submit'}
  </button>
</form>

Sources: README.md:142-168