Semantic form actions, and easier progressive enhancement

[Rich-Harris]

updated proposal below: #5875 (comment)

updated updated proposal below that: #5875 (comment)

---

SvelteKit has always cared about progressive enhancement, i.e. making it easy to build apps that work with or without JavaScript, which is why we promote things like SSR and native form behaviour. The demo app you get when you run npm create svelte includes a progressively enhanced <form> that allows you to create and edit todo items even if JS fails for some reason.

That said, the ergonomics have been something of a TODO up till now. #3533 contains a discussion of a <Form> component that we might add to SvelteKit, but it's only half the problem — the client and the server need to work together, and right now the server isn't really pulling its weight. The right design has been elusive, but with #5748 almost implemented, things are finally starting to come into focus.

In this discussion I'll propose a new design that improves upon the POST, PATCH, PUT and DELETE functions you might have used with page endpoints (or +page.server.js, as of #5748). This will be another breaking change, but much more limited in scope than the tsunami of #5748 (which we're close to landing).

It's a long read, so you might want to put the kettle on.

tl;dr

As with all such changes, things will make more sense if you read the whole document, so please hold off on commenting until you've done so!

• GET in +page.server.js and +layout.server.js will be renamed to load
• +page.server.js will no longer support POST, PATCH, PUT and DELETE
• We'll create a new route file, +actions.server.js, that exports form actions
• These actions will create sub-routes — ./__actions/[name] — that forms can submit data to
• Page components will receive an actions prop pointing to these sub-routes
• A new <Form> component will make progressive enhancement easy (though is not necessary for form actions to work)

The goal of these changes is to encourage SvelteKit users to build progressively-enhanced apps — not in an eat-your-greens way, but because it's so easy that there's no point not using progressive enhancement — and in so doing contribute to a more resilient web.

While it might seem that we're introducing a bunch of new concepts, we're really refining and clarifying existing concepts — for example you would no longer need to learn the confusing distinction between POST in +page.server.js and POST in +server.js.

What problem are we solving?

Today, you can use a page endpoint (soon to be +page.server.js) to handle form submissions. (Technically, they can handle any HTTP request, but since they're bound to a page they're only really useful for form submissions.) Each page can have up to four actions associated with it, one for each of the POST/PUT/PATCH/DELETE HTTP verbs.

After running the action, SvelteKit renders the resulting page, which involves running all the GET functions (including for +layout.server.js files, which unlike +page.server.js can only have GET), and possibly combining the resulting data with validation errors from the action.

It all works, but the asymmetry between GET and the other verbs is jarring, and even for simple apps the every-action-corresponds-to-a-verb thing can be quite limiting. In the case of the demo app, we have an <input> that changes the text of a todo and a <button> that toggles its done state. Both those actions are patches, which means our PATCH handler has to differentiate between them. Not only that, but because the <form> element only supports GET and POST, we have to muck around with method overrides.

We'd have a better time if our actions were semantic — createTodo instead of PUT, updateTodo and toggleTodo instead of PATCH, removeTodo instead of DELETE — and we went with the grain of the platform by always using POST requests.

Semantic actions

What if we did this instead — exported semantic actions from a new route file, +actions.server.js?

// +actions.server.js
import assert from 'node:assert';
import * as db from '$lib/db.server.js';

const todo = db.table('todo');

/** @type {import('./$types').FormAction} */
export function createTodo({ locals, values }) {
  // SvelteKit automatically calls `await request.formData()` for you
  assert.ok(values instanceof FormData);

  const { id } = await todo.insert({
    userid: locals.userid,
    text: values.get('text')
  });

  return {
    result: { id }
  };
}

/** @type {import('./$types').FormAction} */
export function updateTodo({ locals, values }) {...}

/** @type {import('./$types').FormAction} */
export function toggleTodo({ locals, values }) {...}

/** @type {import('./$types').FormAction} */
export function removeTodo({ locals, values }) {...}

The existence of this file would prevent a route from being prerendered.

FormAction takes an event object which extends RequestEvent with values — the equivalent of await request.formData() — and optionally returns an object with one of the following:

• result means the action succeeded. In a native form submission, the value is disregarded, but if we submitted via fetch then the response payload (which is JSON) includes this result
• location also means the action succeeded. In a native form submission this will result in a 303 See Other response. With fetch, the location is included in the response payload
• errors means the input was invalid somehow and the action was not carried out. In a native form submission, the page is re-rendered and the errors are made available to it (see below for discussion on how that happens); in the fetch case, the errors are again included in the payload. In either case the status of the response defaults to 400; it may be necessary to support a custom status property on the returned object

Returning nothing means the action succeeded but there's no meaningful result to respond with (e.g. in the case of a deletion).

File handling

Some of you will have noticed a problem here. If you have a multipart form that includes (potentially large!) files, we need to do something with them. We probably don't just want to buffer them into memory, which is what happens if you call await request.formData(). One possibility is to add a new app-level function in hooks.js:

export async function handleFile({ locals, file, values }) {
  if (!locals.user) throw error(401);

  assert.ok(file instanceof File);
  assert.ok(values instanceof ReadableStream);

  const url = await send_to_s3(file, values);

  // we can return any representation here
  return { url };
}

We could then make the returned representations available in the action:

/** @type {import('./$types').FormAction} */
export function savePhoto({ values }) {
  const photo = values.get('photo');

  // `photo` is the representation returned from `handleFile`,
  // rather than the `File` object you'd ordinarily find on a
  // `FormData` instance
  assert.deepEqual(Object.keys(photo), ['url']);

  return {
    result: { url }
  };
}

Then again, an app-level file handler might be too restrictive? Would love to hear people's thoughts.

TypeScript

Typed forms are a little tricky. It would be possible to add type safety to values...

/** @type {import('./$types').FormAction<'firstname' | 'lastname', 'avatar'>} */
export function createProfile({ values }) {
  values.get('firstname'); // `string`
  values.get('lastname'); // `string`
  values.get('avatar'); // `{ url: string }`
  values.get('other'); // red squiggly
}

...but impossible to enforce that your form actually contains elements with the correct name attributes (and that name="avatar" only goes on <input type="file">). Open to suggestions, but we may not be able to have complete type safety when working with forms.

Because we're using generated types — i.e. import('./$types').FormAction rather than import('@sveltejs/kit').FormAction — we can use the returned value of handleFile instead of File.

The new actions prop

Exporting an action from +actions.server.js creates a new route — ${routeId}/__actions/${actionName}. For example, to post to the createTodo action, you could do this:

<form action="/todos/__actions/createTodo" method="POST">
  <!-- form contents -->
</form>

That's a little ugly. In reality you'd do this instead:

<script>
  /** @type {import('./$types').Actions} */
  export let actions;
</script>

<form action={actions.createTodo} method="POST">
  <!-- form contents -->
</form>

Generated types (./$types) ensure that the action is valid, and provide autocompletion.

Validation errors

When a form is submitted with invalid data — i.e. the action returns an errors property — we want to show that to the user when the page is re-rendered, along with the previously submitted values.

/** @type {import('./$types').FormAction} */
export function createTodo({ locals, values }) {
  if (values.get('description').length > 50) {
    return {
      errors: {
        description: 'steady on there, Tolstoy'
      }
    };
  }

  // ...
}

This is easy in the trivial case where a page contains a single form, but breaks down if you have multiple forms — if the description for a new or existing todo was found to be invalid in this example, how would you know where to put the error UI and previous value?

<form action={actions.createTodo} method="POST">
  <input name="description">
  <button>add todo</button>
</form>

{#each data.todos as todo}
  <div class="todo" class:done={todo.done}>
    <form action={actions.toggleTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <button>toggle</button>
    </form>

    <form action={actions.updateTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <input hidden name="done" type="checkbox" checked={todo.done}>
      <input name="description" value="">
    </form>

    <form action={actions.removeTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <button>delete</button>
    </form>
  </div>
{/each}

We can solve this by adding data to the form itself as a hidden input, that is contained in the reflected form values. We add a writable form store (the reasons for this choice, as opposed to a readonly store or a prop, will become apparent later) that contains the submitted values (a FormData object) and resulting errors (the plain object returned by the action) like so:

If this seems like a lot of boilerplate, keep reading!

+<script>
+  import { form } from '$app/stores';
+</script>

<form action={actions.createTodo} method="POST">
-  <input name="description">
+  <input hidden name="type" value="new">
+  {#if $form?.values.get('type') === 'new' && $form.errors.description}
+    <p class="error">{$form.errors.description}</p>
+  {/if}
+  <input
+    name="description"
+    value={$form.values.get('type') === 'new' ? $form.values.get('description') : ''}
+  >
  <button>add todo</button>
</form>

{#each data.todos as todo}
  <div class="todo" class:done={todo.done}>
    <form action={actions.toggleTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <button>toggle</button>
    </form>

    <form action={actions.updateTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <input hidden name="done" type="checkbox" checked={todo.done}>
-      <input name="description" value="">
+      {#if $form?.values.get('id') === todo.id && $form.errors.description}
+        <p class="error">{$form.errors.description}</p>
+      {/if}
+      <input
+        name="description"
+        value={$form.values.get('id') === todo.id ? form.values.get('description') : ''}
+      >
    </form>

    <form action={actions.removeTodo} method="POST">
      <input hidden name="id" value={todo.id}>
      <button>delete</button>
    </form>
  </div>
{/each}

Progressive enhancement

So far, so good — we can tell at a glance what our <form> elements are doing, and we can handle data with minimal ceremony — and without requiring JavaScript.

But if JavaScript is enabled we can use it to provide a better user experience — optimistic UI, and updates without reloads. All we need to do is intercept the submit event:

<form
  action={actions.createTodo}
  method="POST"
+  on:submit={async function (event) {
+    event.preventDefault();
+
+    const values = new FormData(this);
+
+    // optimistic UI
+    pending = [...pending, values];
+
+    try {
+      const res = fetch(this.action, {
+        method: this.method,
+        body: values
+      });
+
+      const { errors, result } = await res.json();
+
+      if (errors) {
+        // update the `form` store
+        $form = { errors, values };
+      } else {
+        // invalidate `data`, so the new todo is added
+        await invalidate(location.href);
+      }
+    } catch (e) {
+      // network error! show generic error UI of some kind
+      displayErrorToast(e);
+    } finally {
+      pending = pending.filter((todo) => todo !== values);
+    }
+  }}
>
  <input hidden name="type" value="new">
  {#if $form?.errors.description && $form.values.get('type') === 'new'}
    <p class="error">{$form.errors.description}</p>
  {/if}
  <input
    name="description"
    value={$form?.values.get('type') === 'new' ? $form.values.get('description') : ''}
  >
  <button>add todo</button>
</form>

Reducing boilerplate with <Form>

As hinted at above, this is a fair amount of boilerplate. I dragged you along on that journey so that you could see that it's possible to build progressive enhancement on top of +actions.server.js, but ideally SvelteKit would do a lot of the work for you.

For that, we have <Form>, with which the example above would look like this:

<Form
  action={actions.createTodo}
  on:submit={({ values }) => {
    pending = [...pending, values];
    return () => {
      pending = pending.filter((todo) => todo !== values);
    };
  }}
  on:error={(e) => {
    displayErrorToast(e);
  }}
  let:errors
  let:values
>
  <input hidden name="type" value="new">
  {#if errors?.description}
    <p class="error">{errors.description}</p>
  {/if}
  <input
    name="description"
    value={values.get('description') ?? ''}
  >
  <button>add todo</button>
</Form>

Couple of things to note:

• Earlier, I mentioned that form was a writable store for reasons that would be made clear later. Later is now: because form is a store, <Form> can read and write errors and values directly without you needing to pass them into the component.

• By injecting a hidden input with a unique value...

  <input hidden name="__formid" value="{action}/{i++}">

  ...it can determine during the initial render that the $form value applies to it, by checking if $form.values.get('__formid') matches. In doing so, it can pass let:errors and let:values to the component's contents, making them easier to access. (In extremely weird cases, it might be hard to guarantee that __formid matches between client and server, so as an escape hatch we could allow an id to be set manually.)

• let:errors and let:values can be directly assigned to following a fetch submission, meaning that multiple forms could display validation errors in the progressive enhancement case (unlike with native form submissions, where submission results in a page reload). For example if you attempted to submit one <Form> with bad data then attempted to submit a separate <Form> with bad data, both could show validation errors independently

• $form is primarily a way of getting data back from the server, and as such it represents a single form submission. We could instead make it a map of all form submissions to handle the progressive enhancement case, though it would involve some design compromises

• On <Form> #3533 there was some pushback to the idea of <Form>, mostly because something like <form use:form> would be easier to style. The reason for preferring <Form> is that we can do a lot more boilerplate reduction — with use:form we'd need to do equivalents of __formid/let:errors/let:values ourselves. Styling issues can be solved for the small price of the occasional wrapper element

Validation

You can't talk about forms without talking about validation. But we don't need to spend long on it, as this is mostly a userland concern — do your validation in the action, and the rest will fall into place.

If you need client-side validation as well as validating in the action, just make a function that can run in both environments and use it accordingly:

<Form
  action={actions.whatever}
  on:submit={({ values }) => {
    const errors = validate(values);
    if (errors) throw errors;
    // ...
  }}
>

export function whatever({ values }) {
  const errors = validate(values);
  if (errors) throw errors;
  // ...
}

Replacing GET with load

Replacing POST, PUT, PATCH and DELETE with actions leaves GET by itself, which... is a bit weird.

To recap: in #5748, we moved load into +page.js and +layout.js. We also changed the API of load and GET — their inputs are more closely aligned, and they just return data. In fact, they're almost interchangeable. What if we leant into that? What if we normalised the APIs further, and let you choose between running your load function on just the server (+page|layout.server.js), or on both the server and the client (+page|layout.js)?

This would entail:

• adding fetch to the server-side event. On occasion I've found myself needing to fetch data from endpoints within a GET, which currently entails making a wasteful HTTP request that should instead be translated into a direct function call (in fact, we currently have a convoluted hack for allowing fetch inside GET to work during prerendering), so this feels like a welcome change
• adding depends to the server-side event. We don't currently track the things that cause a +page|layout.server.js to be invalidated, but we probably should, so this too is probably a good thing to add
• either adding session to the server-side event, or throwing an error if a server-side load attempts to read it for the reasons described here
• throwing an error if a load in +page|layout.js tries to access request, clientAddress, platform or locals, as these are only available on the server

If you use +page|layout.server.js, you can access server-only properties (and import server-only modules, i.e. read private env vars etc), and you avoid shipping code to the client. If you use +page|layout.js, you can avoid hitting the server for client-side navigation (useful if your data comes from an external API that doesn't require secrets) and return non-serializable data. The choice is yours.

(Of course, in the rare case that you need both, you can continue to 'chain' them — the output of the server-side load is accessible to the shared load as the data property.)

---

Phew! That was a long read. Appreciate you sticking with it. I'd love to hear your thoughts on this proposal, particularly if you've struggled with forms in SvelteKit previously and this would make a difference to your experience (for better or worse). Thanks!

[PatrickG]

I don't quite understand how it works without js.
Will /todos/__actions/createTodo render the same markup as /todos?

If it redirects to /todos after an action returns errors, the browser would do a GET request and the server would not know that a form was submitted.

Edit: if we need a hidden field anyway, we could put the action in a hidden field as well and do post requests to /todos

[danielh57]

One disadvantage of using a hidden input for the action is that the form submission's request body would need to be buffered and parsed in order for SvelteKit to know which action to route to. In the case of a multipart form with a large file attached that would be tough on the server. Including the action name in the URL means that SvelteKit can find the action handler and still let you control how the request body is handled.

[Rich-Harris]

The request body gets processed before the handler is invoked either way — it would only get buffered in memory if you don't specify a handleFile that saves it to disk or streams it to a bucket or whatever

[danielh57]

If the name of the action is part of the form data like @PatrickG and @FeldrinH are suggesting wouldn't you need to buffer it into memory every time in order to get the action name? Even if there's a handleFile. For example if there's a multipart form and the browser serializes it such that the lengthy file data is before the action name in the request body.

[Rich-Harris]

It's the difference between this...

// responding to POST /a/b/c/__actions/whatever
const segments = url.pathname.split('/');
const page = segments.slice(0, -2).join('/');
const module = await load_actions_module(page);

const result = await module[segments.at(-1)].call(null, {
  ...event,
  values: await process_request_body(request, handle_file);
});

...and this:

// responding to POST /a/b/c
const module = await load_actions_module(url.pathname);
const values = await process_request_body(request, handle_file);
const action = values.get('__action');

const result = await module[action].call(null, {
  ...event,
  values
});

Either way the request body is getting processed before the action is called.

[danielh57]

Thank you for the code samples! It seems like it works because the action handler is completely separate from handleFile. The disadvantage I mentioned would only be relevant if the action handler was responsible for doing the streaming/custom request handling.

[austincrim]

I dig it. +actions.server.js feels like a good separation and I've wanted a server-only load since the beginning.

+page.server.js will only have one export (load) now, correct? It would be nice if we could find another spot for the server-only load and drop +page.server.js entirely since, with the addition of +actions, we are up to 8? file conventions and it's feeling unwieldy to me:

1. +page.svelte
2. +error.svelte
3. +page.js
4. +server.js
5. +layout.js
6. +page.server.js
7. +actions.server.js
8. +layout.server.js

I foresee the most confusion around +page.js, +page.server.js, and +server.js since they have similar names and functions. Ditching +page.server.js would go a long way here, I think.

In any case, I appreciate the fastidious nature of these discussions and offer a big kudos to all the maintainers 🙌.

[Rich-Harris]

When you list them all separately, I agree it looks like a lot. It's a little less overwhelming if you group them...

1. +actions.server.js creates form actions that can be used by layout/page components
2. +error.svelte does what it says on the tin
3. +layout.svelte loads data from either +layout.server.js or +layout.js (or in edge cases, both)
4. +page.svelte loads data from either +page.server.js or +page.js (or in edge cases, both)

Meanwhile

5. +server.js makes it an 'endpoint', and will never appear alongside the others.

In all these cases, the .server makes it clear where the code runs (and we'd like to add a rule that files ending .server must always only run on the server, so you can't e.g. accidentally import utils.server.js into +page.svelte). It definitely does seem a little redundant in the +actions case. I tend to think the increased clarity probably justifies the redundancy, but I hear you.

Calling them +page(.server).js and +layout(.server).js makes it clear that they supply data to +page.svelte and +layout.svelte; changing them to +server.load or +load.server would make that harder to grok I think.

Digression: does a separate +actions.js make sense? (Probably not)

---

You could imagine a case where you want to handle form submissions by interacting with an external API, rather than doing something on your own server. In that case, maybe you'd want an action that ran entirely in the browser in the progressive enhancement case, but could also run on the server?

// src/routes/foo/+actions.js
export async function doTheThing({ values }) {
  // runs directly inside the browser if invoked by `<Form>`, but
  // runs on the server following a native form submission
  await fetch('https://someapi.com/blah', {
    method: 'POST',
    body: values
  });
}

This is probably a nonsensical idea but I had to write it down.

---

One possibility would be to allow +server.js files alongside pages, as suggested in #5875 (comment); POST and PUT etc would be of type RequestHandler, as they are, but it would also accommodate FormAction functions (as long as they avoided those reserved names, plus load if we shoved that in there too). I think it would be a net loss for clarity though.

I actually like having all these files in the directory — it makes it super easy to tell at a glance what features a given route is using, without having to spelunk through the code itself. (Also, not that it should carry undue influence over design decisions, but SvelteKit having easy access to that information without needing to conduct any static analysis on the actual code is very helpful.)

[CaptainCodeman]

+server.js makes it an 'endpoint', and will never appear alongside the others.

Why can't a page and an endpoint co-exist?

This means that SvelteKit will potentially be unable to support certain URL structures that may be used by existing apps, precluding it from being used for any upgrade. Content negotiation to retrieve HTML, JSON, XML, or anything else isn't that uncommon, it's part of the HTTP spec (https://www.rfc-editor.org/rfc/rfc2616.html#section-12).

It would be a shame if SvelteKit had an arbitrary rule that prevented certain URLs from being used.

[danawoodman]

I think I understand the "why" but I agree that it now limits the flexibility of a Kit app quite a bit and also will introduce confusion from people expecting this type of behavior to work. Yes, the compiler panicing when they co-exist will help, but limiting this feels a bit of a step backwards in terms of flexibility and power

[Haffi921]

Excuse me, I'm a hobby developer so my opinion might not jam with professional concerns. Please keep that in mind.

However, I wanted to ask: Besides the contextual difference between +server.{js|ts} and +actions.server.{js|ts}, what is the functional difference between them? Meaning that, besides one being an endpoint and the other connected to pages, do the differ at all in what functions can reside within?

I ask because my idea would be to rename +server.{js|ts} to +actions.server.{js|ts}, thus alleviating the "similar names" confusion. (I also think the problem with +server.{js|ts} is a UX one; that we already have so many ...server.{js|ts} files that is defacto a partial descriptor, not a full one. The +server.{js|ts} file feels more ambiguous to me next to all the other options).

The list @austincrim and @Rich-Harris both outlined here would then become:

1. +actions.server.{js|ts}
   • Creates form actions for layout/page components
   • Is an endpoint for a route when standing alone
2. +error.svelte
   • Does what it says on the tin
3. +layout.svelte loads data from:
   • +layout.server.{js|ts} or +layout.{js|ts} (or in edge cases, both)
4. +page.svelte loads data from:
   • +page.server.{js|ts} or +page.{js|ts} (or in edge cases, both)

Now one thing I might be misunderstanding is that in this proposal +actions.server.{js|ts} would actually have functions with descriptive names instead of GET, POST, etc. I would still argue that the confusion seems to stem from the naming of +server.{js|ts} as API endpoints, and that a name like +api.server.{js|ts} would be better.

[jeremymeadows]

+server.js makes it an 'endpoint', and will never appear alongside the others.

When running the dev server, having a +server.js in the same route as a +page.server.js worked perfectly fine (when there was no GET handler), but it threw errors when trying to build for Node. I don't know how long it would've taken to find that issue if I didn't find this thread because it doesn't seem to be stated in https://kit.svelte.dev/docs/routing#server. It would be great if it could be made to work somehow, but otherwise, I think that it should be more explicit that a page file and a server file are mutually exclusive.

[flavioosh]

Overall, I think this is a great proposal. The separate actions makes things much easier to understand, and the GET to load replacement in the *.server.js files would definitely make things easier to understand.

One thing I don't think would be good is the singular file upload handler in the hooks; I can foresee at least some wanting to do different things with files in different actions. If the tradeoff in this case would be having to await the FormData, I think it's a better one than the singular hook. There might be some other solution, like separating the files out of the FormData into a different variable that is awaitable, but not sure if that would work.

[Giggiux]

I believe too that this is a great proposal, and also that singular application hook may be limiting.

What if the handleFile hook function is just another exported function in the actions file? So that the usual behaviour of awaiting for FormData is replaced only if this function is exported?

[CaptainCodeman]

I don't imagine any "pre-submit" hook would be on the cards? It's way more efficient to stream large uploads direct to cloud storage using a signed URL rather than through the web server. You just need to request the URL to upload to first.

[Rich-Harris]

I didn't cover this in the post, because it isn't a fleshed out thought and I don't want to sound like I'm committing to this, but one thought I had was that if we had locally-scoped hooks — which people ask for periodically — then you could put your handleFile logic there:

// src/routes/+hooks.js
export function handleFile(file) {
  // app-level logic
}

// src/routes/foo/bar/+hooks.js
export function handleFile(file) {
  // scoped logic
}

That seems preferable to a reserved export from the actions module, and would give you the flexibility you need without forcing you to export the same handleFile from multiple actions modules that sit in the same subtree.

Good point about signed URLs @CaptainCodeman. Can you POST form data directly to a signed URL, or do you need to stream the body itself? IIRC it's the latter, which means this is a JS-only feature, so I guess you could do this...

<form
  method="POST"
  action={actions.getSignedURL}
  on:submit={({ values }) => {
    const file = values.get('file');
    values.delete(file);
    return ({ result }) => {
      send(file, result.url);
    };
  }}
>

...though it feels kinda gross. My brain is drawing a complete blank as to how you're 'supposed' to do this stuff, and if there's something the framework should do to enable this sort of thing then I think we should probably do it.

[CaptainCodeman]

You can normally control what the server storage will accept / should expect when creating the signed URL, but for large files (where it makes more sense to do this) it's preferable to use resumable uploads (put + content-range) which would then be into JS only land.

[CaptainCodeman]

the locally scoped hooks would be sweet 💯

Nice to have code together instead of in the global hooks

[danielh57]

I like this proposal and the functionality it provides, but I'm a little confused by the varying treatment of request methods. It seems like it may lead to having different rules for handling requests that are made in different contexts. One thing that's nice about the web is that requests are just requests, but if I'm reading this correctly it doesn't feel like that anymore – there's a big layer of abstraction and indirection around how each request is handled.

For the sake of comparison there's similar functionality in .NET Core that makes action requests feel more consistent with other requests. You can write a template that looks like:

<form method="post" asp-page-handler="updateTodo">
    <!-- ... -->
</form>

That non-standard asp-page-handler attribute will be processed and the form will render with its action attribute modified to include the handler you want (just like the Form component above does). The framework will handle the request with a method called OnPostUpdateTodo(). If you don't include a specific handler, a regular OnPost or OnGet gets called and you can handle the request however you'd like. It's basically sugar over the manual way of dispatching your request handler to more specific functions based on the provided action.

The example uses some conventions that are specific to .NET and the principles behind their web framework, but I hope it still demonstrates the possibility of routing requests and still keeping things closer to the web's simple underpinnings. By contrast, the proposal above feels more complex to me.

[CaptainCodeman]

The hidden form state also gave me ASP flashbacks 😄

[Rich-Harris]

To be clear, you can POST (or GET! though please don't 😅) data to a POST handler in +server.js, and you retain complete control over the request and the response. This is really just sugar that makes life easier.

Side-note — I'm not familiar with .NET but that asp-page-handler stuff makes me 😬 — presumably for that to work without JS the server has to return completely different markup than what you authored

[danielh57]

I'll re-read to understand how this proposal is just sugar, because with my first read it seemed to add more concepts than I was expecting. But maybe I got tripped up by the meaning of the different +-files since we haven't had the chance to try them and internalize their function.

Side-note — I'm not familiar with .NET but that asp-page-handler stuff makes me 😬 — presumably for that to work without JS the server has to return completely different markup than what you authored

Yeah that's correct, .NET's web framework is a traditional MVC framework along the lines of Rails, Django and Laravel so the template is fully processed on the server. The output can be quite different from the input and it's up to users to control the complexity 😐

[PatrickG]

Side-note — I'm not familiar with .NET but that asp-page-handler stuff makes me grimacing — presumably for that to work without JS the server has to return completely different markup than what you authored

I'm not familiar with .NET either, but I assume that it also just adds a hidden input field.

[luisgabrielm]

I think this is a very interesting area and a good proposal to sveltekit. Forms always seemed more difficult than they should be to me.

I still don't understand all the points that were proposed so I'll reread it before making other comments. But if I understood corretly +actions.server.js will only deal with form actions right?

Do you thinking renaming it to +forms.server.js or +formActions.server.js would make it more clear?

If I was learning sveltekit and saw +forms I would immediately associate it with forms and I then see it deals with forms submissions. In my mind +actions could mean a lot of different things.

[j4w8n]

All the ".server" files just looks very noisy. I don't see what they add.

If I need to know what the actions file does, making it longer doesn't tell me anything more.

If I'm understanding all of this, naming it +actions.server.js tells me this code only runs on the server-side. That's the connection between all of the files with server in them.

+page | layout | error.svelte are only client-side
+page | layout.js can run on both if needed

[bato3]

+page | layout | error.svelte are only client-side

wrong, they can be rendered on client side or SSR

remember:
.svelte are rendered (to simplify: returns HTML)
.js/.ts are run, and return: data | error | redirect

All the ".server" files just looks very noisy. I don't see what they add.

Because people had a problem with where the code could execute. I consider this a great move.

[j4w8n]

@bato3

+page | layout | error.svelte are only client-side

wrong, they can be rendered on client side or SSR

remember: .svelte are rendered (to simplify: returns HTML) .js/.ts are run, and return: data | error | redirect

Ah, thank you, I see now. I just watched a video about it. If code is in a script tag of context="module" then it's ssr and the client won't see that javascript. I think I got confused because things like the $session store are exposed to the client. And the fact that the html is seen on the client side. So it might have been more accurate for me to simply say that the svelte files are not server-side only.

[CaptainCodeman]

If code is in a script tag of context="module" then it's ssr and the client won't see that javascript

No, this can also run on the client as well.

[j4w8n]

If code is in a script tag of context="module" then it's ssr and the client won't see that javascript

No, this can also run on the client as well.

Oh wow. I didn't realize how ignorant I was about all of this.

So if I have a module script section for server side stuff, should I just put all of the javascript in there; instead of having both script sections? Or are there use-cases for having js code, which runs on the client, in the module script section?

Maybe I justneed to do more research.

[PatrickG]

With this design, we could allow +server.js next to +page.svelte files.
So when you don't want to use the <Form> component & +actions.js, you don't need a separate route for your endpoints.

That would also allow us to drop the page.server.js file, because we could put the server-side load function into +server.js

[Rich-Harris]

Interesting — what's a situation in which you'd need that? It feels easier to just have a sibling foo.json route than to muck around with accept headers (also, we'd need to figure out whether +server and +actions can co-exist, and what gotchas await if we do that). At least with my implementer's hat on, the current 'a route is either a page or an endpoint' dichotomy feels much simpler.

[dummdidumm]

Mhm interesting thought indeed.

Advantages:

• One less file name to learn (two if you count the layout)
• no need to create a different folder
• the "page endpoint" terminology could be easier to grok or entirely go away in favor of just "endpoints", who can under certain circumstances also help your page directly

Disadvantages:

• "if you happen to have a page next to it, you can also expose a load function from it" - is this intuitive/easy to explain? I think it's ok

Re "can it coexist with +actions - I'd say yes, since actions are on a different URL, so they don't interfere with each other.

[dummdidumm]

Just realized one problem with getting rid of the +X.server.js files - layouts. If there's one (or more, in the case of named layouts) how would that look like with one +server.js file? The load functions would all be in there and there would need to be some naming scheme for them.

[madeleineostoja]

I won't pretend to understand the implementation difficulties, but in terms of user experience I really like the idea of just using +server.js next to a page to handle serverside load, and being able to colocate an api endpoint next to a route if you want

[CaptainCodeman]

a route is either a page or an endpoint' dichotomy feels much simpler

But it would be a new restriction making the routing less flexible and unable to support certain requests./

You may have an existing site that uses content negotiation and would like to migrate to SvelteKit and keep the existing URL structure.

[j4w8n]

I can dig it. It's a bit funky that some server-side-only files would exclusively support load, while the server-side-only server.js file exclusively supports verbs. But then again, server.js is off doing its own non-page route thing. So from that perspective, only supporting load in the page route js files does, in-fact make sense.

(Just had to think that one through while I was typing)

One thing I wasn't clear on - SvelteKit will auto-create the ./__actions/[name] sub-routes, correct?

[Rich-Harris]

Yep, the routes are created automatically (one aspect of this that I didn't call out in the post is that __actions would basically be a reserved word in routes)

[nikfp]

Regarding the discussion on File Uploads and placing the logic into hooks.js, something about placing that logic at that location makes me nervous. I would love to hear further feedback from others on their thoughts as well.

I totally see the point of putting it there for simplicity, and it's reminiscent of using Multer in Express from so long ago. However, it's likely that developers will need some decent education if this proposal continues as described to make sure they are using it correctly. So the first thought on this is I wouldn't expect that to be there, and would expect a route for the upload instead.

Second thing that comes to mind, by replacing the file in formData with a handle to the file or some other representation of it, you run the risk of deviating from expectations (at least in my mind), and being close to what people expect is what makes Svelte so nice to use. So by the time you get out of the hooks and into the route that was called, you now have a documentation burden to educate developers on how to get their file info, and the docs have to be very clear and bold as to how the handleFile hook will behave. In addition whatever the developer did to the file inside the handleFile hook would need to be considered. I for one, would expect the form data I received in the route to match expectations and would need decent guidance as to how it would change.

This brings me to a third thought: If files are handled in a hook, you then have to put all your validation, handling, etc. in that hook as well. Probably fine if you have something like and Avatar jpg upload and that's it (or other simple scenario), but when you get into larger apps I can see issues popping up. With more uploads and more reasons to upload, different permissions on files size and type by user, multiple file storage locations based on x-y-z, uploads to multiple routes from the client, etc. etc. - suddenly all of this is still handled in the same hook and you have a cascade of if(...) statements. I can see it getting ugly. Possibly doing something like sequence() could shore this up a bit, but it's still a bit divorced from the reason you are uploading, represented semantically in the route URL for the upload. In contrast, handling this at the route level means that you only need to check for conditions required in that route and you reduce maintenance burden and brain damage.

Just my 2c and others might see this vastly differently. FWIW the rest of this proposal is great. I think some hard thinking needs to go into how Semantic Actions would be implemented, but it would solve an issue I have already run into with limitation on verbs used in endpoints, just like you described. I'm currently solving this using a /trpc endpoint and calling into it as needed, which gets things working but breaks progressive enhancement as a side effect. A bona-fide "Sveltekit" way would be preferred.

[Rich-Harris]

See #5875 (reply in thread) for a discussion of scoped handleFile.

I hear you about the types — if someone is expecting values to be a vanilla FormData object then it might be surprising. One possibility is to break values up into fields: Map<string> and files: Map<ReturnType<typeof handleFile>> (except not actually Map, because we need getAll from FormData which Map doesn't have):

/** @type {import('./$types').FormAction<'name' | 'email' | 'password', 'avatar'>
export function register({ fields, files }) {
  const name = fields.get('name'); // string;
  const email = fields.get('email'); // string;
  const password = fields.get('password'); // string;

  const avatar = files.get('avatar');

  await db.createUser({ name, email, password, avatar: avatar.url });
}

[bato3]

1. I think we should allow load in +actions. (Duplicate error reported at compile stage) similar - see also in PatricG
   I have my doubts about this, but the number of files I need - it annoy me. And it's convenient to have everything in 1 file.

2. I find it necessary to make it clear that using +server.js with something else is a mistake. (any: page, laout). BTW, a multi-level structure should be used in presenting new file names, eg.: opposite - see also in PatricG

routes
      +layout.svelte
      +layout.server.js
      /api/foo
              +server.js
      /foo
          +page.server.js

3. Forms: Can Svelte provide CSRF verification directly?

4. Someone already mentioned that the HTTP method is not checked in + actions. Will it be possible to explicitly declare that the data is to come with the method, for example: PUT / GET instead of the default POST. (And hopefully the default is POST, if not, an error will be reported).

4b. How to implement in the actions reality: (Users must be able to send themselves a filtered list of products.)

<form action="/search" method="GET">

[Rich-Harris]

I think we should allow load in +actions

This would be very confusing, as it's very explicitly not an action — it does a completely different job. See #5875 (reply in thread) for comments on having separate files

I find it necessary to make it clear that using +server.js with something else is a mistake

The framework will error immediately if you do this, you won't be left guessing

Forms: Can Svelte provide CSRF verification directly?

CSRF handling was part of the proposal in #3533, but it turns out that since all modern browsers include the Origin header for POST requests, it's unnecessary — you can just add this in handle:

/** @type {import('@sveltejs/kit').Handle} */
export const handle = async ({ event, resolve }) => {
  if (event.request.method === 'POST') {
    if (event.request.headers.get('origin') !== event.url.origin) {
      return new Response('not today, satan', { status: 403 });
    }
  }

  return resolve(event);
};

Will it be possible to explicitly declare that the data is to come with the method, for example: PUT / GET instead of the default POST. (And hopefully the default is POST, if not, an error will be reported).

<form> only supports GET and POST. Form actions will only support POST. Anything else will result in a 405.

How to implement in the actions reality: (Users must be able to send themselves a filtered list of products.)

This would work as it does today — your /search route just needs to load data based on url.searchParams

[bato3]

Thanks for your patience for a fool like me ;-)

load in +actions

I understand you are looking at this in terms of features.

I would like to logically group database operations. As a last resort, I can have my-actions.js and import functions from it in the correct +actions, +load files. Though I'd rather avoid it.

CSRF

I added my vision in #72. In short: it should not be a comprehensive solution, but parts that work together.

4b.

I liked this solution so much that I wanted them everywhere. :-)

[bato3]

I see one big problem with this proposal: This approach means that if I want to have a classic application and provide REST api at the same time, the code will have to be duplicated.

I suggest that it be possible to use with <form action="/post/3/_action/updatePost> and $.put ('/post/3')

---

Eh... I just realized that the directory based router sucks. I will have to split the logic of createPost and updatePost into 2 separate levels. (or use tricks with submitting edited ID in the form...)

This cane be doing with the trick: /post/_action/[id]/updatePost...

Unfortunately, I have no idea for an implementation so that such tricks do not destroy the beauty and simplicity of this and the previous change.

---

//edit:

Can be possible use actions name in HTML in snake-format?

I'm prefer urls like _action/create-post instead _action/createPost

[TheOnlyTails]

This is great! I can't say I fully understand the actions change, but it looks good to me.

The load and GET merge is awesome! ever since page endpoints were introduced I didn't realize why they couldn't be the same, and I'm glad to see this idea come to fruition.

[qwacko]

Looks like an interesting proposal and I can see the benefits of it (and it also points to the benefit of folder based routing instead of file based) but had a couple of clarifications / questions.

1. I think this is super close to some of the functionality that comes with trpc and that is great. Just to confirm that I understand correctly, the changes are focused on forms but there is no reason you can't use these outside a form? I know the key reason is focused on progressive forms, but if this gave me a type-safe (or at least type aware) way to easily access server side functions, I think the benefits are much bigger than in a form. Currently I am looking at graphql + code-generator, but maybe this will negate the need for that.
2. Do the action functions get the session, and hooks is called just like and other endpoint?
3. How would the access to the actions work from within a component outside the routes tree? Since complex applications quickly lead to form inside components, I assume prop drilling would be the best way, but then you may lose some of the benefits of the proposal (and accessing the types may be a challenge). The new ability to colocate components may also help on this aspect but there are always reused forms on different pages, which this may not support
4. Have you considered the possibility of having "global actions" (maybe a +actions.server.js file in the routes root directory). The reason I ask is that a number of functions are likely to turn up in multiple locations and so I can see myself having alot of actions files which are simply mapping the same functions through ( or maybe export * from "$lib/..."). This may also make accessing these functions from components simpler. I think it may add unnecessary additional complexity to the change and deviate from the core reason for the change, but maybe this is also a logical conclusion of the change.

Thanks.

[dummdidumm]

Re 1: No this only works for forms. I had the same thought initially, that this could be sweet for the general use case to tightly integrate frontend/backend in a type-safe way (it only works with JS enabled though, but that's ok for some apps). On the other hand, we already have endpoints, which you can use for the same, so now there are multiple ways to do the same. It also could be that some people find the solution lacking and still end up using their own GraphQL/tRCP/something similar.
Maybe we should look at how we can make +server.js more type-safe instead (although I don't have good ideas of the top of my head)?

[Rich-Harris]

Do the action functions get the session, and hooks is called just like and other endpoint?

You can think of this...

// src/routes/foo/+actions.server.js
export async function x({ values, ...event }) {
  const { errors, data } = await doSomething(values);
  if (errors) return { errors };

  return {
    location: `/foo/${data.id}`
  };
}

...as sugar for this:

// src/routes/foo/__actions/x/+server.js
async function x({ values, ...event }) {
  const { errors, data } = await doSomething(values);
  if (errors) return { errors };

  return {
    location: `/foo/${data.id}`
  };
}

export async function POST(event) {
  const values = await event.request.formData(); // not quite, because of `handleFile`, but close enough
  const result = await x({ ...event, values });

  if (result.errors) {
    event.setHeaders({
      'set-cookie': `__form=${serialize_form(result.errors, values}`
    });
  }

  const location = (!result.errors && result.location) ?? '/foo';

  return new Response(303, {
    headers: { location }
  });
}

How would the access to the actions work from within a component outside the routes tree?

Have you considered the possibility of having "global actions"

export let actions would involve prop-drilling, yeah. In practice I think you'd rarely have to pass the prop more than a single level though.

One possible addition to the proposal that would solve both concerns would be to have a $page.actions map that's equivalent to $page.data. I don't know how likely it is that you'd need to access global actions in practice though, so it'd probably be worth holding off on that until we have some real world data.

[lukaszpolowczyk]

Reducing boilerplate with

On #3533 there was some pushback to the idea of , mostly because something like would be easier to style. The reason for preferring is that we can do a lot more boilerplate reduction — with use:form we'd need to do equivalents of __formid/let:errors/let:values ourselves. Styling issues can be solved for the small price of the occasional wrapper element

@Rich-Harris I must note my suggestion Targeted Slots - sveltejs/rfcs#68
Targeted Slots would be ideal for the problem in this thread.

I previously cited Declarative Actions, but the author agreed that Targeted Slots solves his problem completely, solving other problems as well.

<script>
  import { Form } from '$app/navigation';
  /** @type {import('./$types').Actions} */
  export let actions;
</script>
<Form
  action={actions.createTodo}
  on:submit={({ values }) => {
    pending = [...pending, values];
    return () => {
      pending = pending.filter((todo) => todo !== values);
    };
  }}
  on:error={(e) => {
    displayErrorToast(e);
  }}
  let:errors
  let:values
>
  <svelte:element slot="form"
    class="flex flex-column p-4 mt-2"
    id="nativeFormELement"
  >
    <input hidden name="type" value="new">
    {#if errors?.description}
      <p class="error">{errors.description}</p>
    {/if}
    <input
      name="description"
      value={values.get('description') ?? ''}
    >
    <button>add todo</button>
  </svelte:element>
</Form>

On the surface it looks usual, the magic of the proposal happens inside - in Form with Targeted Slots syntax.
Syntax description - sveltejs/rfcs#68

Simplified Form:

<script>
  let form;
  let errors;
  let values;
  export let action;
</script>
<slot {errors} {values} />
<svelte:element targeted:form this="form" bind:this={form} {somethingAction} {/*somethingEventsDispatch*/}/>

Where Form, does with the binded form, whatever it wants. Also with its children, like <input/>.

To understand how this is supposed to work, read the Targeted Slots syntax.
It also has more capabilities.

Originally posted by @lukaszpolowczyk in #3533 (comment)

---

And in general, I like the changes very much, especially the actions. :)

[dummdidumm]

I understand people's reservations against a separate file for this:

• One more file name to learn and type
• Harder to colocate code in the same file: You get the data in load in +page.server.js but modify it in +actions.server.js

What if instead the actions are part of +page.server.js (or +layout.server.js)?

• One less file to learn
• Colocation of load and your actions
• Possible page and layout actions are split which is good because they very likely have nothing in common (so essentially, colocation the other way round)

Theoretically we can make it possible this way to also support actions inside +page.js/+layout.js with the same advantages and drawbacks as load inside there.

The drawback of "some names are reserved" is negligible for me - by then you probably know these already and name clashes are close to 0 because the reserved names have nothing "actionable" in their names.

[Rich-Harris]

I think reserved names is a real issue, but to make the conversation we were just having with @dominikg public, we could solve it by having

// +page.server.js
export const actions = {
  createTodo: async ({ values }) => {...},
  updateTodo: async ({ values }) => {...},
  toggleTodo: async ({ values }) => {...},
  removeTodo: async ({ values }) => {...}
};

Pros of export const actions:

• one less file
• it's likely that if you're reading/writing from/to a database, your load and actions will share some code (or at least a reference to a database client, etc) and this would make it easier to co-locate that code, rather than having it in a third module imported by both +page|layout.server.js and +actions.server.js
• it gives us the option of putting handleFile in +page|layout.server.js (without worrying about having a reserved name in +actions.server.js) rather than essentially forcing us to add scoped +hooks
• it makes it clear which actions belong to a +page.svelte and which belong to a +layout.svelte or +layout-foo.svelte

Pros of +actions.server.js

• the separate file makes it clear that this route supports actions, without us needing to read the code
• putting handleFile in +hooks (where it applies to everything in the affected subtree) probably makes more sense anyway
• having actions spread across +page.server.js, +layout.server.js and +layout-foo.server.js might add clarity, but it's also slightly more work (we now need PageActions and LayoutActions and LayoutActions.foo types)
• this is slightly more speculative, but with my Vercel hat on, i'm thinking about a future in which we want more granularity about where code runs. it's possible to imagine cases where you want functions that write to a database to run next to your primary database and respond once the write has been replicated, but you want functions that read from the database to run on the edge, where they can get data from a read replica. If you have load (reads) in one file and actions (writes) in another, it's very easy to do that sort of thing — you could (say) have export const region = 'iad1' in your actions file and export const region = 'edge' in your page/layout file. It gets a little trickier if everything is in the same place

[madeleineostoja]

I really like this proposal! Not only because it's one less file (maybe it's just my preference, but I would much rather deal with one more reserved word than one more file, since there are already a bunch being introduced and that caused enough friction on its own), but because colocating actions & load for a page makes a lot more sense in my brain, even if they don't share much or any logic. There's also something satisfying about one file returning the result of load and the "result" of export const actions to page props

Probably a bad idea for reasons I haven't considered, but could you support both? Export an actions const in page.server.js for light work, or have a dedicated +actions.server.js if you need the separation?

[dummdidumm]

I agree with all the pros for export const actions in +page/layout.server.js and think this is a great solution. The cons are negligible for me:

• "see at a glance this uses forms" is not something I would want to know like that. I also could be using forms "on my own" in which case it's a false negative
• regions: we still can do that using exports like loadRegion and actionsRegion
• handleFile: if we have scoped hooks it probably belongs in there but that's orthogonal to this for me

I wouldn't want two things to do the same though as suggested in the previous comment

[ivanhofer]

I really like the idea of making forms easier to handle 👍
Multiple well named actions can make it easier to understand what happenes than just the HTTP verbs alone.

Here are some comments on the proposed solution:

reactivity

Will values be reactive? I don't think so, because it is not a store, right?
In the code examples a value of e.g. a input field gets prefilled like this:

<input
   name="description"
   value={values.get('description') ?? ''}
>

The value of the input field does not get bound. How would I do a validate-while-you-type functionality?
From what I understand, values are only updated whenever the form get's submitted.

Also errors would need to be a writable store in order to push custom validation errors.
Or the form could expose a function to add an error to a certain field.

optimistic ui

All the examples above show invalid (or incomplete) JavaScript syntax when it comes to the optimistic UI feature. The pending variable get's never declared. So I'm a bit confused. Would this be an integrated concept or is it up to the user to decide how to handle this?

standalone components

Can we keep them? For me it is not really clear if they are replaced by +actions.server.ts or if they stay as described in #5748.

actions prop

From the code examples above I saw that the actions prop get's automatically passed to a route or/and layout?
It is easy to work with if your form is in the +page.svelte or +layout.svelte, but you would need to pass it down the component-tree if you would split your page into different components.
What if instead you export the Form component from a generated ./$form that already contains the typed actions?

<script>
   import { Form } from './$form'
</script>

<Form action="createTodo" method="POST">
  <!-- form contents -->
</Form>

Where the action attribute can only accept an enumeration of defined actions from +actions.ts. createTodo then would be mapped inside the component to ./__actions/createTodo.

I'm not sure if it is possible with the the rootDirs option to also generate runtime code that would export the Form component. The TypeScript docs show an example of an .ts file, but it mostly describes that it is useful for types.

[Rich-Harris]

How would I do a validate-while-you-type functionality?

Maybe <Form> takes a validate function, and a prop that determines whether it runs on input (as-you-type) or change (on blur, and when interacting with e.g. arrows on a numeric input)?

Would this be an integrated concept or is it up to the user to decide how to handle this?

pending is something you'd declare. I think this sort of thing probably has to be in userland, there are too many possible patterns for it to be fully declarative.

standalone components

Not sure what you mean by this. Are you referring to standalone endpoints? If so, yes, they're served by +server.js, though the current proposal doesn't allow them to existing in the same route directory as +page files.

What if instead you export the Form component from a generated ./$form

I think it's important that people can use <form> instead of being forced to use <Form>, so for this reason I think actions are preferable. See #5875 (reply in thread) for comments on prop-drilling etc

[ivanhofer]

Maybe <Form> takes a validate function, and a prop that determines whether it runs on input (as-you-type) or change (on blur, and when interacting with e.g. arrows on a numeric input)?

That validate would then be used for all fields. And I can imagine that there are probably some forms wher a field should be validated as-you-type and some others on blur.

Is it bad practice to not use the native FormData and to make values a writable store and to use two-way databinding on the form fields?

Or maybe an action on the input field itself would be a better approach.

<Form ... let:validateOnBlur>
   <input
      name="description"
      value={values.get('description') ?? ''}
      use:validateOnBlur={(value) => {
         if (value.length < 10) {
            throw new Error('Must contain at least 10 characters')
         }
      }}
   >
</Form>

Since validateOnBlur is tied to the form component it knows what value to pass to the callback function and what to do when the callback function throws an error.

validateOnChange is probably a second action the form could provide. Are there more? Maybe just a general validate function where you need to pass the event-type?

<input use:validate={'blur', (value) => ...} />

---

I think it's important that people can use <form> instead of being forced to use <Form>, so for this reason I think actions are preferable. See #5875 (reply in thread) for comments on prop-drilling etc

The generated file could also export the actions object.

<script>
   import { Form, actions } from './$form'
</script>

But you are probably right, that it is not that likely to pass the prop down more than a single level.

Another "issue" that popped into my mind:
If I want to submit a form that is not part of the actual route, I would need to write the forms action manually, which

• looks ugly because it involves the usually hidden __actions path
• is error prone, if the route would change in the future

An example would be a newsletter subscription form that is visible on more than a single page.

Not sure how to tackle this but In my opinion at least a check for invalid rooutes on relative form action urls should exist

[madeleineostoja]

Could we keep export let actions and have sveltekit create a uuid/hashed action query param, so there's virtually no chance of collision either with other query params by the user or other actions on other routes that haven't been sanitised after sloppy routing?

<script>
  export let actions;
</script>

<form method="POST" action={actions.create}>
 ...
</form>

With the action becoming action="?[uuid-generated-by-kit]"

[Rich-Harris]

It's an interesting idea but I think it's all downside unfortunately:

• the UUID isn't human-readable, making debugging harder
• if you're enumerating over all url.searchParams for some reason (instead of using specific known params), you don't know what to ignore
• 'virtually no chance' !== 'no chance' — if there ever was a collision it could result in some deeply weird and hard-to-track-down bugs

[madeleineostoja]

There are answers to those points:

• Prefix the id so it's readable, so it becomes something like action-[name]-[id]
• A prefix would allow you to ignore when enumerating
• A true uuid would have zero chance of collision

You're right that it's a bit magical though. I do still prefer it to keeping plain strings and exported action names in sync, and I really liked the original idea of a page "consuming" exported actions like it does with load data.

[madeleineostoja]

P.S. Sorry for the ninja edits on my reply, came back to it a bit later and realised I still like the idea lol

[danawoodman]

What if it instead is just an object like:

{
  create: "?_action=create",
  toggle: "?_action=toggle"
}

Kinda like how rails gives you URL helpers so you don't have to manually type out strings. Added benefit is the app will fail to compile if you type the wrong/non-existent action name.

[yousufiqbal]

I like everything about this proposal except one. The thing is that whenever we wanted to declare a function in SvelteKit whether it be component, page endpoint, standalone endpoint, hooks, we declared it using function declaration. It never needed to me a method of an object. It's the Sveltish way.

I think your previous proposal in which functions don't need to be a method of action object was better. I don't care if it's in individual file or in +page.server.js. It should be in Sveltish way.

[dummdidumm]

I can understand that, however you can also look at it from this point: Every export from those files is a feature, and actions are such a feature. There are also non-function exports today, prerender fro example.

[PatrickG]

Every other exported function has a predefined name.
export function addItemToList() {} could be a helper function or an action.

[f-elix]

I really like the direction this is going.

However there is still something I don't understand: How would I get validation data (errors and fields) back from another page's action handler when JS is disabled?

In the /login example from Rich's latest comment, how would I get back the username error if my form is in the root layout? The query string parameter doesn't work in that case, because the page's url can be different from the action.

[Rich-Harris]

Not sure I understand what you mean by rewriting the request to a GET — if the user POSTs to /newsletter but you want to keep them on /, wouldn't you need to return a redirect response after running the handler?

[CaptainCodeman]

Wouldn't errors be rendered into the HTML response? The need to do a redirect to a GET is only after a successful POST, so the form isn't re-submitted if the user refreshed the page. Without the redirect you don't have the problem of passing the validation errors if JS is disabled.

[david-plugge]

Im pretty sure this proposal solves that specific Problem. Subscribing to the Newsletter is an Action on the Index Page, so it should be handled by an Index Page Action.
The errors object could be an object with the Actions as Keys so every Form has it's own Namespace.
I think thats a pretty neat solution, love the idea of Actions!

[f-elix]

Sorry I kinda blurted this all out and I probably wasn't very clear.

I omitted in my explanation that as long as JS is not loaded, the POST request is made to the current url, not the actual action. That way, we get a page refresh on the current page.

Here is a simplified version of the hook (copyRequest creates a new Request from the provided request and options):

const form: Handle = async ({ event, resolve }) => {
	// Make sure its a form request
	if (!isFormRequest(event.request)) {
		return resolve(event);
	}

	// The request will have been posted to the current page, so get the actual action url, 
        // provided as a hidden input in the form
	const formData = await event.request.formData();
	const actionUrl = formData.get('_action');

	// Make sure we get a json response from the real endpoint
	request.headers.set('accept', 'application/json');

	// Create a copy of the request with a modified url
	const requestCopy = copyRequest(request, actionUrl);

	// Post to the actual endpoint
	const response = await fetch(requestCopy);

	// Redirect if needed
	if (isRedirectResponse(response)) {
		return response;
	}

	// Extract response data
	const data = await response.json();

	// Add the data to locals so we can pass it to the client
        // We also namespace the data to the form action
	event.locals.actionData = {
		[actionUrl]: data
	};

	// Change the request to a GET request to the same url
	const pageRequest = copyRequest(request, null, {
		method: 'GET',
		body: undefined
	});

        // Resolve the event with the modified request
	const pageResponse = await resolve({
		...event,
		request: pageRequest
	});

	return pageResponse;
};

This is the only way I found to make this work but I don't like it very much. I feel like I'm going against the framework here, but the result is there. I can have a newsletter form anywhere on my site, and the current page will always be re-rendered with the form validation errors, without having to navigate away.

I just hope there is a way to bake this into Sveltekit so I can trash the above code :)

Does that make more sense?

[david-plugge]

@f-elix maybe this is a solution to your problem?

[CaptainCodeman]

Re: having a <Form> component ...

Remember that it's not the only way to set a form action and method. They can also be set on individual <button> or <input type="submit"> elements via the formaction and formmethod attributes.

Use-case maybe having a single form with buttons for submitting changes or deleting.

[harrylaulau]

[harrylaulau]

And right after posting I have realised I did not address anything regarding the searchparams vs hidden field lol. So instead I would propose is that possible to use a cookie instead? Still this idea seems bad as if so it would require js to work?

[madeleineostoja]

What benefits would this add over any other proposal, other than more required files and folders?

[harrylaulau]

sorry for being a bit out of clue. It was a bit late here and I did not type before thinking through. As I brush my teeth I realise I was just complicating things lol. I would delete this post instead

[harrylaulau]

Sorry for the above comment. Instead after thinking through I would like to suggest the following few things:

1. I really like that we could finally separate load from server and client. However as they serve similar usage and mostly only only one of them would be used at a time, maybe we can have a +page.load.js file exporting client and/or server functions for client and server side load respectively?

// in +page.js, or we rename to +page.load.js
// exporting either one or both of the functions below
export async function client (){ /* client side load */ }
export async function server (){ /* server side load */ }

2. After moving the server side load and client side load into the same folder (as described above), maybe we can rename the +page.server.js into +page.form.js or +page.action.js as the semantic functions would only be used by forms. Also we don't need to export wrapped inside a actions object anymore as no server side load is in this file.

// in +page.server.js, or we rename to +page.form.js or +page.actions.js
export async function create ({ /* fields and other props */ }){ /* logic for this action */ }
export async function delete ({ /* fields and other props */ }){ /* logic for this action */ }
export async function update ({ /* fields and other props */ }){ /* logic for this action */ }

3. Then to target different form functions of the page, I bias to using hidden form fields more only because I used like that in past project. In such case people using <form> element can opt into these semantics action by adding the hidden form field themselves. If they only need a single form for that page, then they may also not include the hidden form field and maybe only exporting a default function in the action file.

<form method="POST">
    <input type="hidden" name="action" value="create"/>
    ...
</form>
<form method="POST">
    <input type="hidden" name="action" value="delete"/>
    ...
</form>
<form method="POST">
    <input type="hidden" name="action" value="update"/>
    ...
</form>

or with the value in a button (would need to decide precedence in this case if it collide with hidden input fields above)

<form method="POST">
    <button type="submit" name="action" value="create">Create</button>
    ...
</form>
<form method="POST">
    <button type="submit" name="action" value="delete">Delete</button>
    ...
</form>
<form method="POST">
    <button type="submit" name="action" value="update">Update</button>
    ...
</form>

or if only a single form

// in +page.server.js, or we rename to +page.form.js or +page.actions.js
export async function default ({ /* fields and other props */ }){ // logic for this action }

<form method="POST">
    <button type="submit">Default</button>
    ...
</form>

[david-plugge]

1. I guess it's done like this because the file would be loaded on the Server and Client which means we cannot use any secret data eg Private env variables as it would be exposed to the Client.
2. That is way cleaner than exporting an object in my opinion, i dont mind an extra file in that case.
3. Maybe the Input Name should be prefixed to not collide with Inputs the User May define.

[harrylaulau]

Yes the server secret should not be included in Client side and splitting by file would be best to avoid misconception. What I thought was as Rich has described client and server side load is rarely used at the same time and even they are both used, maybe the framework can diff the two functions for imports etc and it is now already capable of not including $env/*/private in client side code. Still this might be unnecessary to implement and may cause confusion lol.

[Rich-Harris]

Combining server and client code in a single file is a non-starter. Some frameworks do do this, but it's a terrible practice, because it relies on hard-to-understand compiler magic (you'll hear it described as 'tree-shaking', inaccurately — it works by disregarding the semantics of import) and comes with an array of footguns. It's also much harder to understand where stuff is happening when client and server code is interleaved.

[madeleineostoja]

What Rich said, intricacies of getServersideProps in clientside route files in Next caught me out more than once

[david-plugge]

Maybe it is possible to generate something like this:

type Action = Readable<{
	// the types can be generated from the action file
	errors: Record<string, any>;
}> & {
	name: string;
	values: Record<string, any>
	enhance: (form: HTMLFormElement) => void;
}

• name: a unique name for the action
• enhance: a svelte action that enhances the form element. It handles the submit event and populates the errors to the readable store.
• values: previous input values (only needed for ssr)
• errors: the errors generated by the action

The actions can be defined in a seperate folder like src/actions. The path + filename resolves to the actions name.
One problem i see with this structure is loosing the types for params.

/src
	/actions
		/auth
			/signin.ts --> this generates an action with the name 'auth-signin'
	/routes
		/+page.svelte

/src/actions/auth/signin.ts

import type { Action } from './$types';

export const action: Action = async ({ body, url } ) => {
	if (!body.get('username') {
		return {
			status: 403,
			errors: {
				username: 'please enter your username'
			}
		}
	}

	return {
		status: 200,
		// no redirect needed in this example
		// redirect: '/'
	}
}

$app/actions/auth/signin

const name = 'auth-signin';

export const action = {
    subscribe(fn) {
        const store = getAction(name);
        return store.subscribe(fn);
    },
    get name() {
		return name;
	},
    get enhance() {
        const store = getAction(name);
        async function handleSubmit(this: HTMLFormElement, ev: SubmitEvent) {
            const res = await fetch(this.action, {
                method: this.method,
                body: new FormData(this),
            });
            const data = await res.json();

            if (data.errors) {
                store.set({ errors: data.errors });
            } else {
                store.set({ errors: {} });

				// invalidate to load data
				// this should only reload the current url path or custom paths
                invalidate()
            }
        }

        return function (node: HTMLFormElement) {
            node.addEventListener('submit', handleSubmit);
            return {
                destroy() {
                    node.removeEventListener('submit', handleSubmit);
                },
            };
        };
    },
};

/src/routes/+page.svelte

<script lang="ts">
	// or maybe export  with the same name as the file eg signin ?
	import { action as signinAction } from '$app/actions/auth/signin';
</script>

<form method="post" action="?sveltekit-action={signinAction.name}" use:signinAction.enhance>
	<input type="text" name="username" value={signinAction.values.username} />
	<p>{$signinAction.errors.username}</p>

	<button type="submit">Submit</button>
</form>

myAction.name could also be in the form of sveltekit-action=<the action name> to shorten it down to

<form method="post" action="?{signinAction.name}" use:signinAction.enhance>

That way the query param can be changed in the config file in case a user really wants to use that prefix.

The server can look for the query param and handle the request if an action with the name is found.

This may seem a bit too magic but i like the idea of not beeing limited to use an action in just one place.

things that would change

• removes the need for the prop error
• use actions and show errors wherever you want

[david-plugge]

With the usage of an Action component that sets up the form it would end up like this:

<script lang="ts">
	import { Action as SigninAction } from '$app/actions/auth/signin';
</script>

<SigninAction let:errors let:values>
	<input type="text" name="username" value={values.username} />
	<p>{errors.username}</p>

	<button type="submit">Submit</button>
</SigninAction>

or this:

<script lang="ts">
	import { action } from '$app/actions/auth/signin';
	import { Form } from '@sveltejs/kit';
</script>

<Form {action} let:errors let:values>
	<input type="text" name="username" value={values.username} />
	<p>{errors.username}</p>

	<button type="submit">Submit</button>
</Form>

[bencates]

I really like both the original proposal and this addition to it! I'd like to build off the idea.

First, I really like the idea of colocating the server actions in +page.server.ts. It might be nice to also co-locate the client-side enhancements in +page.ts.

// in +page.ts or +layout.ts
import { invalidate } from '@sveltejs/kit'
import type { PageLoad, PageActionHandlers } from './$types';

export const load: PageLoad () { /* ... */ }

export const actions: PageActionHandlers = {
  // `fields` instead of `body` to mirror the server API.
  async login({ fields, post }) {
    // Throwing `invalidate` here sets `$action.errors` on the page. Throwing
    // `error` and `redirect` will also behave as expected.
    if (!fields.get('username')) {
      throw invalidate({
        username: 'please enter your username'
      })
    }

    // `post` is a thin wrapper around `fetch` with the URL and `method: POST` already set. 
    // If we don't want to do anything with the response we could just `return post(fields)`
    const Response: res = await post(fields)

    if (res.ok) {
      const { token, email } = await res.json()

      // do something useful with the auth token

      // any return value is deep merged into the relevant `$action.values` store
      return { email }
    }
  }
}

This function would be called automatically by the actions.login.enhance Svelte action. This nicely mirrors the proposed server API, it gives developers an idiomatic place to put client-side logic that can still be progressively enhanced during SSR if the client JS breaks, and it groups the client-side form submission logic with the page loading logic where it (arguably) makes more sense.

<script lang="ts">
  // Receive this layout or page's actions as a page prop
  export let actions;
  $: ({ signIn } = actions);

  // Or, if you're on a different page or need to have your submit handler inline
  import { createAction } from '@sveltejs/kit'
  const signInAction = createAction('/?action.login', ({ fields, post}) => {
    // Same API for the submit handler here
  })
</script>

<!-- `action.toString()` returns the full action path -->
<form action={signIn} use:signIn.enhance>
  <!--
    `$action.values` is a writable store in case you need to bind it directly to
    an input value or otherise manipulate it manually. It doesn't have to be
    bound and probably won't be in most cases.
  -->
  <input name="username" bind:value={$signIn.values.username}/>
  <button type="submit">
</form>

<!-- $action.errors is a readable store that can be used anywhere on the page -->
{#if $signIn.errors}
  <dl class="error">
    {#each Object.entries($signIn.errors) as [field, error]}
      <dt>{field}</dt>
      <dd>{error}</dd>
    {/each}
  </dl>
{/if}

We should also support keying actions so they can be used in loops.

<script lang="ts">
  export let data: import('./$types').PageData;
  export let actions: import('./$types').PageActions
  $: ({ update } = actions)
</script>

{#each item in data.items (data.items.id)}
  [@const action = actions.update.key(data.items.id)]

  <form {action} use:action.enhance>
    <!-- ... -->
  </form>
{/each}

actions.update.key(123) creates a new action with the path ?action.update=123. This has the side benefit of removing the need for a hidden field in the form itself. The action's key is available to both server and client handlers as the { key } attribute of the handler's argument.

import type { ServerActionHandlers } from './$types'
import { getItemById } from '$lib/db.server'

export const actions: ServerActionHandlers = {
  async function update({ key, fields }) {
    const item = getItemById(key)
    // ...
  }
}

In any case, this looks like it's shaping up to be an excellent feature!

[david-plugge]

Glad you like my idea!

I´ve been playing around with some ideas and this is what a came up with.
https://github.com/david-plugge/sveltekit-actions

irst, I really like the idea of colocating the server actions in +page.server.ts.

I prefer that aswell and i´m pretty sure its possible to implement in my solution. The actions name can be generated from the path + its name.

One thing i like about my implementation is that every action can be called from anywhere. An example would be a subscribe form provided by the layout that is available on multiple pages.

[david-plugge]

A key is actually very important to be able to report errors to a specific form when there are many forms with the same action name. Didnt think of that yet.

[lacherogwu]

Svelte becoming dirty, with all the great features and enhancement I feel like it's time to take a step back and look at everything from above again. I've heard every one of Rich's talks and saw where the pain points he wants to cover with this awesome framework, and how it should be intuitive to people who just know the bare bones of the web language. and when I've looked at the recent changes seems like it's going a bit backward in this case. more and more svelte-specific rules, more helpers, and less native code.

I don't say it's bad, but I think it might be a bit off-target.

Obviously, you created an amazing project here, but we are here to improve it by sharing our constructive criticism.

[kuchaguangjie]

Same feeling

[jmullaney]

I honestly think it's a mistake to move forms and form submission away from an HTTP API.

If you cover few cases it can be simple, but you still need to expose HTTP to cover all the other cases.
If you cover many cases it becomes complex -- as it approaches the capability of HTTP it also approaches the complexity of HTTP.
Yet it isn't HTTP. It ends up some big chunk of API for devs to learn, just to do something they already know how to do though HTTP and even after that it hasn't made anything easier.

The worst case is you end up with something of decent capability of middling complexity.
Why worst case? It will appear to be the "right way" to do forms, devs will learn it and use it, and it will probably seem OK for a while. But the issues from the limitations will mount. Eventually most devs will realize they're in a dead end and have to spend time and effort to get out.

I understand the motivation -- we all want forms to be easier -- but I think this would be creating a honeypot trap of an API, albeit unintentionally.

At least make it wholly optional and let a page have a POST handler with HTTP request and response. And try to understand and clearly document the limitations up-front, so devs can make an informed decision about opting-in.

[CaptainCodeman]

This is exactly what I think. I want to use HTTP. That's the base layer and provided via endpoints.

Anything else should operate inside of that, so maybe helpers and / or conventions used within the endpoint methods. That can be a mechanism to define which form action but it's just a string value, it doesn't really need to be part of any framework. Just export an enum from somewhere if you want to ensure consistency. But ultimately what are we really talking about? Isn't it just a switch statement to call different functions from inside the POST method based on that string? I don't think I need a framework for that, it's just "different", but not really adding much IMO and I think there is huge value in people learning and understanding how things actually work.

Supporting different HTTP methods for more semantic form requests is already common and usually done via a custom http header or URL search parameter and middleware (which could either be app-wide or per route if available). Again, it's not something that needs to replace the HTTP endpoint, it's just augmenting it so you may not need to have a switch statement inside POST.

[harrylaulau]

To have non form endpoint/ endpoint with full control. I think server.ts fulfill the job? I think Semantic form actions can achieve better code splitting for complex forms. If only a simple form / want to handle the form post request manually, I think a default case which only helps to destructure formData ( or even no pre handling at all, just original request) could do, such that almost if not all use case could be fulfilled?

[jmullaney]

I think we want something that integrates with sveltekit's page rendering.

[jmullaney]

Aside from my general comment, I have this suggestion:

The original proposal makes a distinction between "result" and "errors". They are handled differently and produce a different outcome. I think the updated proposal carries this through (I might have missed something), and even potentially adds a third thing, "fields".

e.g., returning "errors" for a native form submission causes the page to rerender, with the additional errors information made available. But validation "errors" aren't the only kind of information a form submission might generate that you'd want to re-render with. Yet "result" is only returned for fetch submissions.

I think these could be unified, making this mechanism more consistent and more flexible:

A form action handler could return an object with data property and optional status. With native forms submission, the page is rerendered with the data properties made available. If you have validation errors, you have a child property called "errors". (If you want to reflect form fields, you can have a child prop for that too.) For fetch submission, the whole returned object would be returned as JSON in the response body.
As before, the form action handler can return an object with "location" property to redirect.

Note, the result of a form action handler now looks and acts a lot like a load. Those can be unified as well. data returned from form action handler is added to the "data chain" (at the front makes sense to me -- edit: on second thought, I'm not sure -- maybe after layout data but before page server load? IDK). And either change load to return an object with "data" or "location" (like form action handler), or have form action return "data" directly and throw a redirect like load -- the former makes more sense to me (what does throw a redirect even mean?), but either way is OK by me).

[yousufiqbal]

Eagerly waiting for some action on this. I know the community is working double its time. But since it's a big change and migration tires everyone, the more it happens earlier the better. Love you @Rich-Harris

[madeleineostoja]

It’s only been a few days since the last reply in this discussion, and there are still several points that need to reach consensus and be finalised. Comments asking to hurry up don’t help anyone

[madeleineostoja]

Looks like there's a PR in the works for this now, is there any word on what was settled on for query params? I'm still concerned with clashes and keeping string values + function names in sync.

[Rich-Harris]

We're still finessing things, and haven't written everything up just yet because we're finding that certain details (such as action return values) look different when viewed very close up, and it's easier to discuss those aspects with code in front of us.

That said, for query params I'm a big fan of @Azarattum's idea in #5875 (reply in thread):

<form method="post">
  <!-- calls this page's default action -->
</form>

<form method="post" action="?/foo">
  <!-- calls this page's `foo` action -->
</form>

<form method="post" action="/login">
  <!-- calls the login page's default action -->
</form>

<form method="post" action="/login?/register">
  <!-- calls the login page's `register` action -->
</form>

It's concise, very unlikely to conflict with app developers' requirements (though there's always default + hidden input field + switch statement as an escape hatch if you need it), and does a good job of communication 'foo is a child of this page' and 'register is a child of the login page'.

[madeleineostoja]

I like it!

[david-plugge]

Love it!
Just wondering how we are able to determine which form the submitted data belongs to in case of multiple forms with the same action. Just check for a value in the submitted store I guess?

I like the idea of the handleFiles hook, but in case I got it right there is no way to validate the data before. So in that case the file is saved even if other data is missing or invalid. Maybe add a new parameter like getFiles that calls the hook manually. To give even more control over what files are actually saved something like const file = await files.get('x') could work.

That way a different handleFile function can be passed as a second param to be able to save to some other service

[dummdidumm]

You can return anything you want from handleFile, for example a function which you call after you have validated the data:

export function handleFile(..) {
  return { upload: () => ImageServer.upload(..) };
}

/** @type {import('./$types').Actions */
export const actions = {
  default: ({ fields, files }) => {
    if (everythingValid(fields)) {
       files.get('picture').upload(); // this is typed!
   }
   //..
  }
}

[Azarattum]

Let me dream for a second a describe how I would imagine my ideal API.

First and foremost, I think SvelteKit should still have the first class support for HTTP verbs. So, we can write RESTfull APIs in it that can be consumed by things other then Svelte's web frontend. But action proposal is really nice for readability and form handling. So, we can't we have both, where each approach might be optional and up to a project's requirements. This way we can still write APIs the way we used to, but would eliminate unnecessary boilerplate (like a giant switch statement in POST handler) when needed.

So, I have multiple proposals:

Make handlers importable functions

import { GET, POST, ACTION } from "sveltekit";

GET(() => {
  //implementation
});

POST(() => {
  //implementation
});

ACTION(async () => {
  //implementation
});

ACTION("create")(async () => {
  //implementation
});

Benefits:

• Only a single indentation level for the code that actually matters (compared to 2 in export const actions = { create: ... }
• Type inference for FREE! (we can get rid of /** @type {import('./$types') */ nonsense for both TS and JS, since arguments of a function are inferred automagically!)
• More readability, since we instantly see what we deal with in CAPS, then refer to the implementation
• ACTIONS vs HTTP opt in. We can use one or both depending on the project requirements
• Beautiful symmetry between http and action handlers (therefore ACTION is in caps)
• No export boilerplate. The handlers can be automatically registered by the framework after the function call.
• Maybe it would be possible to make ACTION feature completely tree shakable for projects written in pure HTTP calls (by looking for ACTION imports)

Return regular JSON by default

When a browser requests a page it adds the accept: text/html header. This should signal the framework to render the page using GET API function as a load function. Otherwise return a plain JSON response.

/**
 * Regular get request, returns JSON by default. If a route was hit
 *  with `accept: text/html` then it loads the page with the result of this function.
 */
GET(async ({ locals }) => {
  // JSON data is returned
  return {
    todos: await db.getTodos(locals.userid)
  };
});

Benefits:

• When using fetch in JS we get the API response without any extra boilerplate
• Supported by all major browsers (they add accept: text/html by default for all page requests)
• We can get a sensible website representation with tools like curl by default (JSON is much more readable in terminal, and in the most cases it's what we would want anyway)
• Dynamically fetch data for the current page with as little as fetch("").then(x=>x.json()) is the kind of magic people want the frameworks for
• Solves Bring back support for content negotiation (allow +page.svelte & +server.ts to co-exist) #5896

Use symbol for returned headers

We use headers symbol exported from sveltekit to add headers to any our response (including errors and redirects). This will put all the returned state in a single place.

import { ACTION, error, redirect, headers } from "sveltekit";

ACTION("create")(async ({ fields, url }) => {
  const to = url.searchParams.get("redirectTo");
  if (to) {
    throw { 
      ...redirect(to),
      [headers]: { "X-From": url } 
    }
  }

  if (!fields.text) throw error(400, "Text shouldn't be empty!");
  const todo = await db.addTodos(fields.text);

  // This returns a plain JSON. BUT! `headers` is a unique symbols which is filtered
  //  from the response and sent as headers. Being a `Symbol` it insures uniqueness,
  //  avoids conflicts, allows all the returned data to be in one place (compared to
  //  the `setHeaders` function) and allows for clean and concise syntax.
  return {
    ...todo,
    [headers]: {
      "set-cookie": await createSession()
    }
  };
});

Benefits:

• Improved readability and intuitiveness. (It make sense to "return" headers)
• No conflicts or reserved words. (Since we use a JS symbol)
• Flexible. Can be added to return, error, redirect objects.

We keep both HTTP and ACTIONs (so they enhance each other)

Actions are glorified post handler. But we should be able to use them both! A post handler might be a nice middleware for our action. And actions might nicely reduce the code in a POST handler.

/**
 * Regular POST request handler. It also has prepared `action` parameter,
 *  according to whatever convention svelte will have (e.g. `?/action`). This way we can implement
 *  any middleware (like authentication) for every action in this route.
 */
POST(async ({ locals, action }) => {
  if (action.startsWith("admin-")) {
    if (!(await db.isAdmin(locals.userid))) {
      throw error(403, "No Access, Sorry.")
    }
  }

  // If nothing is returned or thrown, proceed to handle ACTIONs
});

/**
 * ACTION is a higher order function which returns a filtered POST handler for a particular
 *  action.
 */
ACTION("create")(() => { ... });
ACTION("update")(() => { ... });
ACTION("toggle")(() => { ... });
ACTION("remove")(() => { ... });

/**
 * Some actions, access to which is managed by the POST handler.
 */
ACTION("admin-dashboard")(() => { ... });
ACTION("admin-logs")(() => { ... });

/**
 * If the first parameter of an ACTION if typeof "function", it is treated as default action.
 *  It is very similar to the POST handler, but it runs only when no other actions are called,
 *  while POST runs before every action.
 */
ACTION(async () => {
  return {
    [headers]: {
      "set-cookie": await createSession()
    }
  };
});

Conclusion

To sum this up, the full code for a route might look like this:

Full Code

import { error, redirect, headers } from "sveltekit";
import { GET, POST, ACTION } from "sveltekit";

/**
 * Regular get request, returns JSON by default. If a route was hit
 *  with `accept: text/html` then it loads the page with the result of this function.
 */
GET(async ({ locals }) => {
  // JSON data is returned
  return {
    todos: await db.getTodos(locals.userid)
  };
});

/**
 * Regular POST request handler by default. But it also has prepared `action` parameter,
 *  according to whatever convention svelte will have (e.g. `?/action`). This way we can implement
 *  any middleware (like authentication) for every action for this route.
 */
POST(async ({ locals, action }) => {
  if (action.startsWith("admin-")) {
    if (!(await db.isAdmin(locals.userid))) {
      throw error(403, "No Access, Sorry.")
    }
  }

  // If nothing is returned or thrown, proceed to handle ACTIONs
});

/**
 * ACTION is a higher order function which returns a filtered POST handler for a particular
 *  action.
 */
ACTION("create")(async ({ fields, url }) => {
  const to = url.searchParams.get("redirectTo");
  if (to) {
    throw { 
      ...redirect(to),
      [headers]: { "X-From": url } 
    }
  }

  if (!fields.text) throw error(400, "Text shouldn't be empty!");
  const todo = await db.addTodos(fields.text);

  // This returns a plain JSON. BUT! `headers` is a unique symbols which is filtered
  //  from the response and sent as headers. Being a `Symbol` it insures uniqueness,
  //  avoids conflicts, allows all the returned data to be in one place (compared to
  //  the `setHeaders` function) and allows for clean and concise syntax.
  return {
    ...todo,
    [headers]: {
      "set-cookie": await createSession()
    }
  };
});

/**
 * The other actions are treated is a similar way
 */
ACTION("update")(() => { ... });
ACTION("toggle")(() => { ... });
ACTION("remove")(() => { ... });

/**
 * Some admin actions, access to which is managed by the
 *  POST handler.
 */
ACTION("admin-dashboard")(() => { ... });
ACTION("admin-logs")(() => { ... });

/**
 * If the first parameter of ACTION if typeof "function", this is treated as default action.
 *  It is very similar to the POST handler, but it runs only when no other actions are called,
 *  while POST runs before every action.
 */
ACTION(async () => {
  return {
    [headers]: {
      "set-cookie": await createSession()
    }
  };
});

[Azarattum]

Also, we might still want to have a LOAD function that runs both on client & server. It would receive data from the GET function (which runs only on server). So, we can put all the handlers into +page.js file. Since all the page.server, server, page, layout.server, page.actions, page.server, page.actions.server etc. gets really confusing really fast...

import { GET, LOAD } from "sveltekit";

/** Runs only on the server */
GET(async ({ locals }) => {
  return {
    todos: await db.getTodos(locals.userid)
  };
});

/** Runs both on client & server */
LOAD(({ data }) => {
  const { todos } = data;
  todos.sort();

  return { todos };
});

[david-plugge]

• Type inference for FREE! (we can get rid of /** @type {import('./$types') */ nonsense for both TS and JS, since arguments of a function are inferred automagically!)

I dont think so since we have generated types. Something like

import { ACTION } from '@sveltejs/kit';
import type { Action } from './$types';

ACTION<Action>(() => ...)

can be done but thats not nice to look at.
If typescript is able to provide different types depending on the importing file, that would be a very clean solution but i don´t know about such thing.
And generating the types would be difficult compared to using exported methods/objects.

Also, we might still want to have a LOAD function that runs both on client & server. It would receive data from the GET function (which runs only on server). So, we can put all the handlers into +page.js file. Since all the page.server, server, page, layout.server, page.actions, page.server, page.actions.server etc. gets really confusing really fast...

The +page.js load method runs on both ends and receives data from +page.server.js load.
Combing server only handlers and client handlers into one file is a bad idea. There are some comments in the discussion about the new routing design.

[Azarattum]

@david-plugge, we can directly generate the typed handler functions and import them:

import { ACTION } from './$kit';

Dynamic type generation would be more difficult indeed without exports. I guess if this is impossible we can prefix each handler with an export and I still will be shorter that the current way.

export GET(() => ...)
// VS
export const GET: Handler = () => ...

Since SvelteKit is a compiler type inference without exports should be possible (although not easy). But IMO the complexity worth the nice API. Check out this dirty example how it would be done with exports.

On the second point

What methods apart from load are in +page.js currently (that run on both sides)? As I understand the load is the only one that runs on the client, therefore I see not reason to put it separately. Ideally you shouldn't need it at all apart from some weird hacks. I think making it an optional special LOAD handler is a nice solution. It would also keep the naming quite simple.

Btw, could you also like the routing design discussion?

[jmullaney]

I think GET and "load" have enough differences that it doesn't make sense to try to unify them.

GET is an HTTP concept: given a GET request, return a response: (url. headers) --> (status, headers, body). GET is the whole request processor.

I think a "load" function is one step in the process of a page GET. A load function's job is to either change to a different page (error page or redirect) or provide data to the loading page. Importantly, there's actually a chain of load functions, from the layouts to the page, from server-only to the "rendering" load (whether on server or client), and then the page rendering happens (if it gets that far).

The processing chain means load has to be able to access data from previous steps and add to or modify it. GET doesn't have the semantics for that.

BTW, I don't specifically have a problem with there being some kind of data-specific GET handler associated with a page, except that (1) it's just confusing; (2) it seems app-specific, so maybe something the framework shouldn't get involved with. (Also, I wonder if the framework doesn't already have sufficient support for this pattern anyway... I'm thinking of a page having a "load" sub-route for this purpose -- there could be, e.g., a ".../mypage/load/+server.js" with a GET request handler, which implements whatever dynamic loading your page wants. You can fetch that from load or dynamically or whatever you want.

[danawoodman]

Thinking out loud here, but I'm wondering if something like this might be possible to further simplify routing?

Using @Rich-Harris proposal as a foundation, I propose considering removing +server files entirely and merging them into +page.server:

// src/routes/todos/+page.server.js
import * as db from '$lib/db.server.js';
import type { FormActions, PageLoad } from "./$types";

export const load: PageLoad = async ({ locals }) {
  return {
    todos: await db.getTodos(locals.userid)
  };
}

export const actions: FormActions = {
  async create({ locals, fields }) {
    await db.createTodo(locals.userid, fields.get('description'));
  },
  async update({ locals, fields }) {...},
  async toggle({ locals, fields }) {...},
  async remove({ locals, fields }) {...},
};

// Endpoints do not respond to requests of type "text/html"
export const endpoints: Endpoints = {
  // Does not pass data to "load"
  async GET(event) {
    // return JSON by default (nice to have, not essential)
    return { hello: "world" }
    // or:
    // return json({...}, { status, headers });
  },
  // Can also return a custom response
  async POST(event) {
    return new Response(
      xml,
      { headers: { "content-type": "application/xml" } }
    );
  },
  async PUT(event) {...},
  async PATCH(event) {...},
  async DELETE(event) {...},
  async SOMETHING_CUSTOM(event) {...},
}

• Removing +server can reduce cognitive load of needing to know the difference as well as allowing pages to live alongside endpoints.
• The returned endpoints can be typed in one go by typing the return value.
• Can check the request type to return different types of responses (ala Rails). Some helpers for this could be nice (eg isJSON(request) or isXML(...)).
• For setting headers on a JSON response the setHeaders helper could be used.
• Almost everyone returning stuff from an endpoint is going to want to return JSON, but you can still opt out by returning a Response

I'm sure I'm missing some things, but having a single +page.server file that can be extended to support API endpoints would be awesome 🤩

[madeleineostoja]

I think if anything this adds more cognitive load, to explain why pure API endpoints have to be “pages”

[david-plugge]

I do think splitting the logic makes sense, but I kinda like the idea of exporting an object with the handlers as it would reduce type annotations to a single one instead of one per method. But then you always have that object even if you just use a get handler.

[Rich-Harris]

forms-proposal.final.v5.final.md

Alright, this thread is overdue for an update. Along with the plentiful feedback on this page (thank you all!) the maintainers have spent hours discussing the fine details of this proposal, and we're excited about where it's all landing. @dummdidumm is in the process of implementing everything in #6469.

I'm going to try and articulate the design as best I can (and as concisely, though as usual there's a lot of ground to cover). Our goal here is to provide a fantastic easy-to-understand experience for the common case (with type safety, where possible), while allowing as much flexibility as people need to solve niche problems.

A +page.server.js can have actions as well as load

In the simplest case, a page has a default action, like this /login example:

// src/routes/login/+page.server.js

/** @type {import('./$types').Actions} */
export const actions = {
  default: async (event) => {
    // ...the user is logged in
  }
};

On the /login page, invoking this action is easy, because in HTML the action attribute defaults to the current page:

<form method="POST">
  <input name="email" type="email">
  <input name="password" type="password">
  <button>Log in</button>
</form>

We can also invoke the action from other pages (for example if there's a login widget in the nav in the root layout):

<form method="POST" action="/login">

A page could have named actions as well as the default one:

// src/routes/login/+page.server.js

/** @type {import('./$types').Actions} */
export const actions = {
  default: async (event) => {...},
+  register: async (event) => {...}
};

We can invoke this action by specifying the name in a query parameter prefixed with /, either in a <form action> attribute or in a <button formaction> attribute:

<form method="POST">
  <input name="email" type="email">
  <input name="password" type="password">
  <button>Log in</button>
+  <button formaction="?/register">Register</button>
</form>

Similarly, this action can be referenced from other pages:

<form method="POST" action="/login?/register">

The actions API

An action function receives an event: ActionEvent that is identical to the LoadServerEvent passed to a load function in a +page.server.js, with two additions:

• fields, which is a FormData object whose values are all strings
• files, which has the same API, but each value is a File in the default case. I'll talk more about file handling below

There are four possible outcomes:

1. an error happens (throw error(...), throw new Error(...), or something unexpected happening in code that your action calls) in which case the nearest +error boundary is shown
2. a redirect happens (throw redirect(...))
3. the action fails, and returns validation errors to the page
4. the action succeeds, and optionally returns some data to the page

1 and 2 are just the same as load. For 3, we briefly discussed something like throw invalid(...), but 3 has more in common with 4 than it does with 1. Crucially, by always returning (rather than throwing) data, we get type safety.

// src/routes/login/+page.server.js

/** @type {import('./$types').Actions} */
export const actions = {
  default: async (event) => {
+    const email = event.fields.get('email');
+    const password = event.fields.get('password');
+    
+    // failure cases
+    const user = await db.getUser(email);
+    if (!user) {
+      return { email, missing: true };
+    }
+    
+    if (user.password !== hash(password)) {
+      return { email, incorrect: true };
+    }
+    
+    // success case
+    event.locals.user = user; // so we can read it in `load`
+    
+    setHeaders({
+      'set-cookie': await db.createSession(user)
+    });
+    
+    return { success: true };
  }
};

Note that the returned data can take any shape (unlike a previous version of this proposal where validation errors had to be in an errors property), and is available to the page via export let form:

<script>
  /** @type {import('./$types').PageData} */
  export let data;
  
  /** @type {import('./$types').Form} */
  export let form; // this is typed, like `data`!
</script>

{#if form?.success}
  <!-- this message is ephemeral, it exists because the page was rendered in
       response to a form submission. it will vanish if the user reloads -->
  <p>Successfully logged in! Welcome back, {data.user.name}</p>
{/if}

Since we returned { email, password, missing } and { email, password, incorrect } objects in the failure cases, we can prompt the user to try again without wiping the original data:

<form method="POST">
-  <input name="email" type="email">
-  <input name="password" type="password">
+  {#if form?.missing}<p class="error">No user found with this email</p>{/if}
+  <input name="email" type="email" value={form?.email}>
+
+  {#if form?.incorrect}<p class="error">Wrong password!</p>{/if}
+  <input name="password" type="password" value={form?.password}>
  <button>Log in</button>
</form>

There's one small detail missing here — the version of the page with validation errors should really have a 4xx status code. To enable that, we add an invalid helper that lets you return a status code along with the data:

// src/routes/login/+page.server.js
+import { invalid } from '@sveltejs/kit';

/** @type {import('./$types').Actions} */
export const actions = {
  default: async (event) => {
    const email = event.fields.get('email');
    const password = event.fields.get('password');
    
    // failure cases
    const user = await db.getUser(email);
    if (!user) {
-      return { email, missing: true };
+      return invalid(403, { email, missing: true });
    }
    
    if (user.password !== hash(password)) {
-      return { email, incorrect: true };
+      return invalid(403, { email, incorrect: true });
    }
    
    // success case
    event.locals.user = user; // so we can read it in `load`
    
    setHeaders({
      'set-cookie': await db.createSession(user)
    });
    
    return { success: true };
  }
};

In the same way that export let data is reflected via $page.data (allowing other components, such as a parent layout, to use the data) export let form would be reflected via $page.form.

Progressive enhancement

To enable progressive enhancement, fetch requests made to an action will result in a JSON response. The four outcomes shown above would have the following representations:

1. an unexpected error happens

500 { "message" : "..." }

(In the throw error(420) case, the status could would be 420 instead of 500.)

2. a redirect happens

200 { "type": "redirect", "location": "/other" }

We have to use a 200 status code for the response because 3xx responses are opaque (i.e. if the server responds with a 3xx, the fetch caller can't access the location header).

3. validation errors

200 { "type": "invalid", "status": 403, "data": { "email": "...", "password": "...", "missing": true } }
200 { "type": "invalid", "status": 403, "data": { "email": "...", "password": "...", "incorrect": true } }

Again, we're using a 200 status code — this time, because we need to distinguish between validation errors and thrown errors.

4. success

200 { "type": "success", "data": { "success": true } }

Additionally, we expose an updateForm function to update export let form (and $page.form and $page.status) to the values they would have had following a native submission — but most of the time you wouldn't use it directly, you'd just use the provided enhance function:

<form method="POST">
  <button>This will reload the page</button>
</form>

<form method="POST" use:enhance>
  <button>This will run the action, invalidate the page's data, and update `form`, but without reloading</button>
</form>

<form
  method="POST"
  use:enhance={({ form }) => {
    // this runs immediately
    
    return ({ error, result }) => {
      // this runs as soon as we get a result
      
      if (error) {
        // an error was thrown, or a network error occurred
        return;
      }
      
      switch (result.type) {
        case 'redirect':
          goto(result.location);
          break;
          
        case 'failure':
          alert('try again dummy');
          break;
          
        case 'success':
          invalidateAll();
      }
    };
  }}>
  <button>This will run the action, invalidate the page's data, and update `form`, but without reloading</button>
</form>

The precise details of the updateForm and enhance APIs haven't been finalised, but you get the idea. By handling the submit event, we get complete control over optimistic UI, concurrent submissions, invalidation timing and so on. (We expect patterns to emerge on top of these primitives for handling common cases like batching invalidations and so on, whether those are in userland or in helpers that are eventually added to SvelteKit itself.)

No <Form> component

Previous iterations of this design relied on a <Form> component, which did magical things to (for example) convert the initial form data into let:errors and let:values.

I no longer think that's the right approach. With this iteration, we can simply provide use:enhance, allowing you to progressively enhance any form (or <button> or <input type="image">, with the formaction attribute!) without having to compromise around styling and so on. Because actions can return any data, associating a submission with a particular form instance is pretty straightforward, in the cases where you need to do that. No magical __formid that gets rendered to a hidden input, or any of that nonsense.

No methodOverride

Today, the way to have multiple actions on a single page is to associate them with specific HTTP verbs — POST, PATCH, PUT, DELETE. Aside from the fact that this is inherently limiting, it's a lie: HTML forms can only be submitted with GET or POST.

To workaround this limitation, SvelteKit adopted the same hack as many other frameworks — a _method query parameter. The idea is that a POST request with _method=PATCH is treated by the framework as a PATCH request. But it's not a PATCH request, it's the HTTP equivalent of three dogs in a trenchcoat.

The only difference between /path?_method=PATCH and /path?/toggleTodo is that the latter actually communicates what's going to happen. No more agonising over which verb is 'correct', or whether it would really be more appropriate for the PATCH to happen in a subroute.

It turns out that RESTfulness is a great quality to have when designing APIs, but neither useful nor achieveable (because of <form> limitations) when building apps. You can of course achieve a fully RESTful API using +server.js files, you might just need to redirect back to a page (and find a way to persist validation errors, and reimplement the _method hack) if you intend to use them as an alternative to actions. (Right now +server.js files can't co-exist with +page files, but that might change in future.)

File handling

Eventually we want to provide a way to deal with uploaded files on a streaming basis. This would consist of a handleFile hook that would take a RequestEvent and a ReadableStream plus some metadata (name, type) and return a custom file representation (which could just be the S3 URL the data was streamed to, or whatever).

This would most likely be a global hook. There was some conversation previously about having it be scoped somehow, but honestly I feel like that's unnecessary additional complexity. In the rare (surely) cases where you want different file handling per route, you can just inspect event.routeId — not pretty, but gets the job done without adding new framework concepts.

All this falls under 'future work'. For now you'd be better off generating signed upload URLs and POSTing directly to them, and that will arguably continue to be true once we have streaming file handling. Effectively, the fields and files passed to actions will just be this until then:

const fields = new FormData();
const files = new FormData();

for (const [key, value] of await request.formData()) {
  if (typeof value === 'string') {
    fields.append(key, value);
  } else {
    files.append(key, value);
  }
}

Cookie handling

This is a complete aside to this proposal, but this is as good a place to call it out as any. When writing the /login example above, I included this code:

// success case
event.locals.user = user; // so we can read it in `load`

setHeaders({
  'set-cookie': await db.createSession(user)
});

This only works if the load code gets the user object from event.locals. But it's quite likely that it instead gets it from event.request.headers.get('cookie'). We're returning a set-cookie header, but that will have no effect on the cookie header that would likely be used in e.g. a +layout.server.js file:

// src/routes/+layout.server.js
import * as cookie from 'cookie';
import * as db from '$lib/db';

/** @type {import('./$types').LayoutServerLoad} */
export async function load({ request }) {
  const cookies = cookie.parse(request.headers.get('cookie') ?? '');
  const user = await db.getUser(cookies.sessionid);
  return { user };
}

I think this is a clear sign that we need built-in cookie management, so that we can instead do this:

// success case
cookies.set('sessionid', await db.createSession(user));

// src/routes/+layout.server.js
import * as db from '$lib/db';

/** @type {import('./$types').LayoutServerLoad} */
export async function load({ request, cookies }) {
  const user = await db.getUser(cookies.get('sessionid'));
  return { user };
}

Relatedly, we had a conversation about replacing setHeaders with the standard Headers interface, so that you'd do this sort of thing:

headers.append('cache-control', 'max-age=300');

I'll draw up a separate issue for that.

[bato3]

What about passing an object like fastify to pass some configuration options?

Cons: The current proposal is simple and transparent. (although file transfer is a bit of a problem)

Pros: It's nice to have. :)

Especially since it could be used to attach actions as a REST-API urls.

/** @type {import('./$types').Actions} */
export const actions = {
	default: {
                // function can be allow to extract slug from url and apply it to data
		rest: [ 'put', ()=>'/api/some/dummy/path'],
		handler({ fields, files }) {
			...
		}
	}
}

[MentalGear]

Since the newest form proposal has no more _method, I was wondering what the "recommended practice" is to apply an operation on a resource. I didn't find anything clear in the guide regarding this.

If I understand correctly, it is advised to "think away" with (simulated) HTTP methods and instead describe outcomes one would like to apply to the REST resource, and use a form action to execute them.

For example, to delete a task, one would have a delete form action next to, for example, an update form action in the same server page. Then the task can be deleted by having a html <button formaction=?/delete>.

Is this correct ?

[dummdidumm]

That's correct. The alternative would be to use +server.js where you have the full HTTP methods arsenal to your exposal - it won't work without JavaScript, though (browser forms only support GET and POST, and GET rarely makes sense).

[205g0]

ChatGPT just told me there's some +actions.server.js which can handle Form Actions from other folders too. Guess it found it here in the earlier discussions but it's not mentioned anymore in the final proposal nor the docs. So, I assume it's gone and Form Actions work only with their paired +page.svelte file and not components from other folders, right?

[coryvirok]

It's mentioned in the tutorial: https://learn.svelte.dev/tutorial/named-form-actions

The action attribute can be any URL — if the action was defined on another page, you might have something like /todos?/create. Since the action is on this page, we can omit the pathname altogether, hence the leading ? character.