docs: clarify that shared `getRequestEvent()` auth helpers need `isRedirect()` handling for `command()`

[hyunbinseo]

Describe the problem

• Redirecting from server hook (with remote command) fails #14858

getRequestEvent() makes it possible to write shared, reusable auth helpers like this: #13582

import { redirect } from '@sveltejs/kit';
import { getRequestEvent } from '$app/server';

export function requireLogin() {
  const { locals, url } = getRequestEvent();

  // assume `locals.user` is populated in `handle`
  if (!locals.user) {
    const location = new URL('/login', url.origin);
    location.searchParams.set('redirectTo', url.pathname);

    redirect(307, location);
  }

  return locals.user;
}

However, redirect() is explicitly disallowed inside command(). If requireLogin() (or any shared helper that redirects) is called from inside a command, the redirect gets caught server-side, serialized, and then the client throws:

Error: Redirects are not allowed in commands. Return a result instead and use goto on the client

Describe the proposed solution

The remote functions docs should show how to safely reuse a redirect()-based helper inside a command()

// server: saveSession.remote.ts
} catch (e) {
  if (isRedirect(e)) return { error: 'UNAUTHENTICATED' as const, location: e.location };
  throw e;
}

// client
const response = await myCommand(data);
if (response.error === 'UNAUTHENTICATED') goto(response.location);

Alternatives considered

SvelteKit could change the client command() runtime to throw something callers can actually inspect, rather than a message-only Error. Then isRedirect() (already a public, universal export) would work in the catch block exactly the way one would intuitively expect:

// client
import { isRedirect } from '@sveltejs/kit';
import { goto } from '$app/navigation';

try {
  const response = await myCommand(data);
} catch (e) {
  if (isRedirect(e)) {
    goto(e.location);
    return;
  }
  throw e;
}

Importance

would make my life easier

Additional Information

No response

[sacrosanctic]

Instead of overloading the docs, we can include this in sveltejs/cli#641

[hyunbinseo]

@sacrosanctic so there will be an auth helper - which works with command - included in the default template?

Or maybe with the better-auth add-on? The minimal template does not include any authentication.

I would love a good example code.

[sacrosanctic]

better-auth add-on comes with a demo. We can include most of the common use cases. and lean onto the community to create niche examples.

[hyunbinseo]

So the current better-auth template doesn't use any auth helper:

export const load: PageServerLoad = (event) => {
  if (!event.locals.user) {
    return redirect(302, '/demo/better-auth/login');
  }
  return { user: event.locals.user };
};

export const actions: Actions = {
  signOut: async (event) => {
    await auth.api.signOut({
      headers: event.request.headers
    });
    return redirect(302, '/demo/better-auth/login');
  }
};

export const load: PageServerLoad = (event) => {
  if (event.locals.user) {
    return redirect(302, '/demo/better-auth');
  }
  return {};
};

I would love a reference auth helper example in the docs as well. (with support for returnTo, etc.)

I implemented my own auth and have never thought about trying the better-auth add-on until now.