DEV Community: Kamran Khan

After every save, I refetch the page I'm on — not page one

Kamran Khan — Fri, 30 Oct 2026 04:17:09 +0000

Here's a bug I've shipped more than once: you edit a user on page 3 of an admin table, save, and the table jumps back to page 1. The edit worked. The user just isn't visible anymore, and for a second you wonder whether it worked at all.

The fix in my starter kit's Users page is one argument: after closing the modal, call fetchUsers(meta.current_page) instead of fetchUsers(1). The modal closes, and the table reloads the page the admin was already looking at, with the fresh data from the server. The edited row is right there, updated. The newly added user shows up too, since the list is ordered newest-first — and if pagination shifted because of the add, the server's meta in the response corrects the pager anyway, because fetchUsers stores res.data.meta alongside the rows.

Delete follows the same rule: after client.delete('/users/' + id), call fetchUsers(meta.current_page) again. Same page. If deleting the last row on a page leaves it empty, that's a real edge case — the honest version of this code would step back a page when the response comes back empty — but the common case, which is what a starter kit should get right first, is staying put.

Why refetch at all, instead of updating the local row optimistically? Because the server is the source of truth for this table, and the list endpoint is cheap. The create response returns the new user, the update response returns the updated user, but patching those into a paginated, sorted list by hand means re-implementing the server's ordering and pagination in the client. One refetch gets you the server's ordering, the correct page meta, and every other admin's concurrent changes, for the price of one GET.

There's a discipline hiding in this: after a mutation, don't guess at the new state — ask for it. Optimistic updates are a performance optimisation, and they're worth it when a list is slow or a mutation is expensive. For an admin table over a local API, the refetch is fast, simple, and never wrong. I save the cleverness for places where it pays.

Staying on the same page sounds trivial. But it's the difference between an admin who trusts the tool — save, see it change, move on — and one who keeps re-navigating to check their own work. Small respect for the user's attention, coded as one argument.

This Users page, the paginated API behind it, and the whole admin panel ship in my Laravel + React SaaS Starter Kit — https://kamranofficial.gumroad.com/l/mhekoig — a $19 one-time boilerplate with Sanctum auth and role-based access, so you don't rebuild this table from scratch.

My sidebar footer is the whole auth UI: an initial, a role badge, and a logout button

Kamran Khan — Fri, 30 Oct 2026 04:16:01 +0000

I didn't set out to design an auth UI. I set out to stop answering the same three questions every time I opened the app: who am I signed in as, what can I do, and how do I get out? All three answers ended up in the same place — the footer of the sidebar, in my starter kit's Layout component.

Here's what sits down there: a circle with the first letter of the user's name, uppercased, falling back to "U" if there's no name yet. Under it, the user's name, and a small badge showing user role exactly as the API returned it — "admin" or "user". And a Logout button.

The initial needs no avatar upload, no image pipeline, no broken-image icon when a profile photo is missing. It's a circle with a letter in it, and it works on day one for every user, including the seeded demo admin.

The role badge is the honest part. It shows the role right under the name. There's no separate "account type" page to visit, no settings screen to dig through. If you're wondering why you can't see the Users link, the badge tells you: you're not an admin. That same isAdmin check (user role === 'admin') is what hides the Users nav link above, so the badge and the navigation can never disagree.

And the logout button does the full job, not half of it. Its handler awaits logout() from AuthContext and then navigates to /login. The logout posts to /auth/logout — which revokes the current token on the server — and removes saas_token from localStorage. Only then does the sidebar navigate to /login. Logging out is not "clear the token and hope"; it's revoke server-side, clear client-side, then move. If the API call fails, the client still clears the token, so a dead session can't linger — but the normal path revokes properly.

The same initial shows up again in the top header, top-right. Same letter, same user, two places. That's not decoration; it's a cheap consistency check. If the header and the footer ever disagreed, something would be wrong with the auth state, and you'd spot it instantly.

None of this is clever. That's the point. A starter kit's auth UI shouldn't need a design system or a profile service. It needs to answer three questions at a glance, in one place you always see. An initial, a role badge, and a logout button that actually logs you out — that's the whole thing, and it's enough.

The full Layout, AuthContext, and token handling ship in my Laravel + React SaaS Starter Kit — https://kamranofficial.gumroad.com/l/mhekoig — a $19 one-time boilerplate, so your next project starts with this already working instead of half-built.

My create endpoint returns 201 and a full user, not a bare id

Kamran Khan — Fri, 30 Oct 2026 04:14:46 +0000

Most create endpoints I see in client codebases return one of two lazy things: a 200 with the new id, or a 200 with a success message and nothing else. Then the frontend has to make a second request to show the thing it just created, or it guesses at the shape and gets it wrong.

In my starter kit, creating a user returns this, every time:

public function store(StoreUserRequest $request): JsonResponse
{
$user = User::create($request->validated());
return response()->json(['user' => new UserResource($user)], 201);
}

Two decisions are packed into those three lines, and both are deliberate.

First, 201, not 200. A 200 says "fine, done." A 201 says "a resource now exists that didn't before." That distinction matters the day you write a frontend that branches on status, or a test that asserts creation actually happened. My register endpoint does the same — 201 with the user and a token — because registration is also a creation, not a generic success.

Second, the full resource, not a bare id. The frontend gets the exact same UserResource shape it gets from the list endpoint and the show endpoint: id, name, email, role, timestamps. No second fetch, no special-case shape for the create response, no moment where the table shows a row with missing fields while it waits for a refetch.

Consistency is the real point. Look at the rest of the controller and the pattern holds: show returns ['user' => new UserResource($user)], update returns the same envelope after $user->update($request->validated()). One envelope, one resource, everywhere. The only endpoint that breaks the pattern is destroy, and it does so honestly — 204 with no body, because there is nothing left to return.

There's a temptation to return more on create: the created record plus a message plus a redirect URL. I resist it. The frontend already knows what it just submitted; what it needs back is the server's version of the record — the id, the stored role, the timestamps — in the shape it already knows how to render.

If you take one rule from this: never make your frontend fetch what your backend already has in its hands. Return the resource you just created, in the shape you always return it, with the status code that says it now exists.

That pattern, along with the FormRequest validation and the role middleware that guard this endpoint, ships in my Laravel + React SaaS Starter Kit — https://kamranofficial.gumroad.com/l/mhekoig — a $19 one-time boilerplate with Sanctum auth, role-based access, and a working admin panel, so you start from these decisions instead of re-arguing them.

My dashboard's "recent users" section is the admin table with the buttons turned off

Kamran Khan — Fri, 23 Oct 2026 04:42:40 +0000

On my dashboard, admins see a "Recent users" section under the stat cards. It is not a new component. It is the same UsersTable the admin Users page uses, rendered with dead handlers:

<UsersTable users={recentUsers} onEdit={() => {}} onDelete={() => {}} />

UsersTable is a dumb component: it takes a list and two callbacks. Hand it real callbacks and you get the admin table. Hand it no-ops and the edit/delete buttons fire into the void, so it renders as a read-only list. Same markup, same columns, zero extra code.

The data comes from the same endpoint too:

client.get('/users', { params: { per_page: 5 } })

One honest note: my backend index() is User::query()->latest()->paginate(15), so it currently ignores per_page and returns the first page of 15, newest first. The param is there for when I wire it up server-side. What matters is that the newest-first ordering makes page one the recent list for free — the "recent users" section is literally the same data the admin page shows, just displayed on the dashboard. And only admins fetch it: the whole section sits behind the isAdmin gate, while regular users get a getting-started card instead.

The point is boring on purpose. The dashboard did not need a second table component, a second fetch shape, or a second set of columns. It needed one dumb component used twice, with the buttons switched off the second time.

This is one of the reuse patterns I bake into my Laravel + React SaaS starter kit — small components with honest props instead of near-duplicate ones: https://kamranofficial.gumroad.com/l/mhekoig

One modal, two modes: my add-user and edit-user forms are the same form

Kamran Khan — Fri, 23 Oct 2026 04:41:50 +0000

My admin Users page has one user form, not two. It is the same modal, driven by a single state value:

const [modal, setModal] = useState(null); // 'add' | 'edit' | null

openAdd resets the form to blanks and sets mode 'add'. openEdit pre-fills name, email and role from the row, deliberately blanks the password, and sets mode 'edit'. Everything else — the inputs, the error rendering, the buttons — is shared.

The mode shows up in exactly the places where add and edit genuinely differ:

<input
  type="password"
  required={modal === 'add'}
  ...
/>

Password is required when creating, optional when editing, with a small "(leave blank to keep current)" note in edit mode. And on submit:

if (modal === 'add') {
  await client.post('/users', form);
} else {
  const payload = { name: form.name, email: form.email, role: form.role };
  if (form.password) payload.password = form.password;
  await client.put(`/users/${editing.id}`, payload);
}

The edit payload strips the password unless the admin actually typed one. This mirrors the backend exactly: the create request requires the password, the update request says sometimes. The frontend and the backend agree on which fields are mandatory in which mode, and that agreement lives in exactly one place on each side.

Two more small things. The submit button reads "Create User" or "Save Changes" from the mode. And closeModal() always resets the form to the empty shape, so opening Add right after an Edit never leaks the previous user's email into the blank form.

I keep reaching for this pattern because the alternative — two near-identical forms — is where add and edit quietly drift apart. One form, one mode flag, and the two modes can only disagree where they are supposed to.

This modal ships as-is in my Laravel + React SaaS starter kit, with the matching backend rules, auth and roles around it: https://kamranofficial.gumroad.com/l/mhekoig

I never hash passwords in my controllers — the `hashed` cast does it

Kamran Khan — Fri, 23 Oct 2026 04:40:50 +0000

Every password write in my starter kit flows through one line on the User model:

protected function casts(): array
{
    return [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
    ];
}

Search my whole backend for Hash::make and you will find nothing. The only Hash call is Hash::check on login, which only reads. Nobody ever writes a hash by hand.

So the register endpoint does this:

$user = User::create([
    'name' => $request->validated('name'),
    'email' => $request->validated('email'),
    'password' => $request->validated('password'),
    'role' => 'user',
]);

The controller passes the raw password straight through and the model hashes it before it touches the database. Same story in the admin create-user flow, and same in the seeder — DatabaseSeeder passes 'password' => 'password' in plain text and it lands hashed. The seeder does not know or care about bcrypt.

Two things I like about this. First, hashing is a decision that can never be forgotten. There is no new controller where someone (me, three months from now) forgets to hash before saving. The wrong thing is impossible. Second, the cast does not double-hash: if the value is already hashed it leaves it alone, so the factory's pre-hashed 'password' stays exactly as it is.

The login side never touches storage:

if (! $user || ! Hash::check($request->validated('password'), $user->password)) {
    return response()->json(['message' => 'Invalid credentials'], 401);
}

Check on the way in, cast on the way out. One job each.

I have stopped treating password hashing as something each controller does and started treating it as something the model guarantees. That is the whole pattern.

Patterns like this one — auth, roles, admin CRUD, dashboard — are what my Laravel + React SaaS starter kit is made of, so every project starts from them instead of rediscovering them: https://kamranofficial.gumroad.com/l/mhekoig

My Dashboard fetches two things at once — and cancels both on unmount

Kamran Khan — Thu, 22 Oct 2026 05:19:51 +0000

My Dashboard page needs two things: the stats for the cards, and the five most recent users for the table underneath. Here's exactly how it loads them:

useEffect(() => {
  let cancelled = false;

  async function load() {
    try {
      const [statsRes, usersRes] = await Promise.all([
        client.get('/dashboard/stats'),
        isAdmin ? client.get('/users', { params: { per_page: 5 } }) : Promise.resolve(null),
      ]);
      if (cancelled) return;
      setStats(statsRes.data);
      if (usersRes) setRecentUsers(usersRes.data.data ?? []);
    } catch (err) {
      if (!cancelled) setError(err.response?.data?.message || 'Failed to load dashboard data.');
    } finally {
      if (!cancelled) setLoading(false);
    }
  }

  load();
  return () => {
    cancelled = true;
  };
}, [isAdmin]);

Three decisions in here that I reuse on every page of the kit:

One: parallel fetches with Promise.all. The stats call and the users call don't depend on each other, so they go out together. The recent-users fetch only runs for admins — everyone else resolves null and the table section never renders. No separate loading states to juggle, one loading flag for the whole page.

Two: the cancelled flag. Every setState after an await is guarded. If the user navigates away mid-fetch, the cleanup flips the flag and the late responses are dropped silently. No "state update on an unmounted component" warnings, no stale data landing on the wrong page. It's five extra lines and it makes every page feel solid.

Three: honest loading and error states. Loading is a centred spinner (animate-spin with an indigo top border). Failure is a rose-coloured box with the API's own message, or a fallback string. No skeletons pretending the data is almost here, no silent empty tables.

And one small human touch: Welcome back, {user?.name} at the top. Dashboards are cold by default; a name costs nothing.

This same shape — Promise.all, cancelled flag, spinner, error box — is copy-pasted into my Users page too. A starter kit teaches by repeating one good pattern until it's muscle memory, not by showing three clever ones.

This Dashboard page ships in my Laravel + React SaaS Starter Kit — the React frontend wired to a real Laravel + Sanctum API: https://kamranofficial.gumroad.com/l/mhekoig

My whole design system is one 30-line CSS file

Kamran Khan — Thu, 22 Oct 2026 05:18:41 +0000

Here's my entire global stylesheet, in full:

@tailwind base;
@tailwind components;
@tailwind utilities;

body {
  @apply bg-slate-100 text-slate-800 antialiased;
}

/* Custom scrollbar */
::-webkit-scrollbar {
  width: 10px;
  height: 10px;
}

::-webkit-scrollbar-track {
  background: #f1f5f9;
}

::-webkit-scrollbar-thumb {
  background: #94a3b8;
  border-radius: 8px;
  border: 2px solid #f1f5f9;
}

::-webkit-scrollbar-thumb:hover {
  background: #64748b;
}

That's it. Three Tailwind directives, one body rule, and a styled scrollbar.

The kit's "look" doesn't come from this file. It comes from repeating the same utility combinations everywhere — rounded-xl bg-white p-6 shadow-sm is my card, text-sm font-medium text-slate-500 is my label. My StatCard component is literally that combo with four accent colour choices. The design system is a habit, not a file.

So why the scrollbar? Because the users table scrolls, and a default browser scrollbar next to an otherwise polished admin panel is the kind of thing that makes a buyer think "unfinished". Ten lines of CSS, one considered detail. Slate track, rounded thumb, darker on hover — it matches the palette instead of fighting it.

I deliberately did not add a component library, a theme file, CSS variables, or dark mode. Not because they're bad — because a starter kit should only ship what it actually uses. Architecture theatre is the fastest way to make a kit feel heavy. Thirty honest lines beats three hundred speculative ones.

The body rule does the real work anyway: bg-slate-100 for the app background, antialiased because un-anti-aliased text on a dashboard looks cheap. Two tokens, applied once, inherited everywhere.

If you're shipping a kit: resist the theme file. Repeat one good combo until it becomes your design system, and spend your CSS budget on the ten lines people actually notice.

This stylesheet ships in my Laravel + React SaaS Starter Kit — the whole frontend (React dashboard, auth pages, admin panel) included: https://kamranofficial.gumroad.com/l/mhekoig

My login page shows the demo credentials — a starter kit has to be runnable in 60 seconds

Kamran Khan — Thu, 22 Oct 2026 05:17:32 +0000

Every starter kit I've bought died in the same place: the login screen. Not because the auth was broken — because I couldn't find a single valid credential to try it with. Buried in the README, step 9, between the queue worker and the mail config. I gave up and closed the tab.

So when I built my own kit, I made one rule: the login page ships the demo credentials in the open.

Here's the relevant part of my Login.jsx:

{import.meta.env.VITE_DEMO_MODE === 'true' && (
  <p className="mt-3 rounded-lg bg-indigo-50 px-4 py-2 text-xs text-indigo-700">
    Interactive preview — sign in with the demo credentials below. Data is simulated.
  </p>
)}

{/* ... the form ... */}

<div className="mt-6 rounded-lg bg-slate-50 px-4 py-3 text-xs text-slate-600">
  <p className="font-semibold text-slate-700">Demo credentials</p>
  <p className="mt-1">
    Email: <span className="font-mono">admin@demo.io</span>
  </p>
  <p>
    Password: <span className="font-mono">password</span>
  </p>
</div>

Two pieces. The box under the form is always there: email admin@demo.io, password password. The banner above the form only renders when the build sets VITE_DEMO_MODE=true, because it makes a claim that's only true in the public preview — "data is simulated", since the demo build runs against an in-memory mock axios client instead of Laravel.

The credentials box isn't gated, because in a real local run those credentials are real. My DatabaseSeeder creates them with firstOrCreate, idempotent, so it works whether you seeded once or five times:

User::firstOrCreate(
    ['email' => 'admin@demo.io'],
    ['name' => 'Admin', 'password' => 'password', 'role' => 'admin']
);

Is printing credentials on a login page a security smell? In a production app, yes. In a starter kit, it's documentation that can't be skipped. Nobody reads README step 4; everybody stares at the login page. The credentials box is the fastest path from git clone to seeing the dashboard.

Two smaller details I kept: the submit button disables and switches to "Signing in…" while the request is in flight (no double submits), and a failed login renders a rose-coloured box above the form with the API's message — deliberately generic, never saying which half was wrong.

If you're building a kit: make the login page teach the login. The README is for the 10% who read it.

This login page is from my Laravel + React SaaS Starter Kit — the whole auth loop (Sanctum tokens, roles, seeded demo admin) ships in it: https://kamranofficial.gumroad.com/l/mhekoig

My user payload includes a field my app can't set: why email_verified_at ships anyway

Kamran Khan — Wed, 21 Oct 2026 04:16:40 +0000

Here is the full UserResource in my starter kit:

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'role' => $this->role,
        'email_verified_at' => $this->email_verified_at,
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

Seven fields. One of them is a lie, or at least an IOU: email_verified_at. My kit has no email verification. No verification routes, no signed URLs, no "check your inbox" screen. For every real user of this boilerplate, that field is null, forever, until the developer adds verification themselves.

So why ship it?

Because API payload shapes are contracts, and this field is forward compatibility bought at the cheapest possible price.

The day you add verification, nothing downstream changes. The resource already emits the field. The React side already receives it. The demo mock mirrors it. Every component that reads a user object already handles a key that happens to be null today and a timestamp tomorrow. The feature lands as backend-only work: routes, mail, a controller. No frontend migration, no mock update, no "why did the user object change shape" debugging across a codebase you did not write.

Removing a field later is the expensive direction. I have seen the reverse too many times: a minimal payload ships, six months later someone adds verification, and the new field ripples through types, mocks, tests, and three components that destructure the user object. Adding a field to an API response is a breaking change for every consumer you cannot see, including consumers of a boilerplate who built on your shape. Shipping the field early means the shape was always the final shape.

Null is honest. This only works because the field is truthfully null, not faked. The resource reads it straight from the model; the model reads it from the column; the column is empty because no flow writes to it. A frontend that shows "unverified" for a null timestamp is correct on day one and stays correct. What I would never do is invent a value, like defaulting it to created_at to make the payload look complete. A placeholder value is a lie that downstream code will eventually trust.

There is a boundary to this habit, and it is worth naming: I ship the field, not the feature. The kit still has no verification flow, no verification email, no UI for it. Shipping the field says "this is where the data will live". Shipping a half-built feature says "this works", and then it does not. One of those is forward compatibility. The other is a bug report waiting to happen.

My rule of thumb for boilerplates: if a field is on the model's natural trajectory and costs nothing to emit, emit it now. Your future self, adding the feature properly, will change one backend file instead of ten files across the stack.

I deliberately left verification (and password reset, and subscriptions) out of my starter kit to keep it shippable, and I wrote about those cuts before. The payload, though, is already ready for the day verification arrives. That is the whole kit's philosophy in one field: cut the feature, keep the shape. The full starter kit is here: Laravel + React SaaS Starter Kit

Three owners of one token: how my AuthContext, my axios client, and localStorage split auth state

Kamran Khan — Wed, 21 Oct 2026 04:15:56 +0000

In my starter kit, the Sanctum token has exactly one name and exactly two modules that touch it. That was a deliberate decision, and it is the reason I can change my auth storage strategy in an afternoon instead of a week.

The name is saas_token. It lives in localStorage. Here is everyone who is allowed to know that.

Owner one: the axios client. Every request passes through a request interceptor that reads the key and attaches the header:

client.interceptors.request.use((config) => {
  const token = localStorage.getItem('saas_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

And a response interceptor owns the "token died" path. On a 401, it clears the key and sends the user to login, unless they are already on the login or register page (redirecting someone off the login page because their non-existent token is invalid would be a special kind of bug):

client.interceptors.response.use(
  (response) => response,
  (error) => {
    const status = error?.response?.status;
    const path = window.location.pathname;
    if (status === 401 && path !== '/login' && path !== '/register') {
      localStorage.removeItem('saas_token');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

Note this happens at the network layer, outside React. No component, no context, no state update involved. An expired token redirects you before React has an opinion about it. And the interceptor still rejects the promise, so a form that triggered the 401 can still show its error state if it wants to.

Owner two: the AuthContext. It holds the token in React state, initialised from the same key, and it is the only place that writes it:

const [token, setToken] = useState(() => localStorage.getItem('saas_token'));

const login = useCallback(async (email, password) => {
  const res = await client.post('/auth/login', { email, password });
  localStorage.setItem('saas_token', res.data.token);
  setToken(res.data.token);
  setUser(res.data.user);
  return res.data;
}, []);

const logout = useCallback(async () => {
  // Best-effort: the session is cleared locally no matter what.
  try {
    await client.post('/auth/logout');
  } catch {
    // Ignore — token is being discarded either way.
  }
  localStorage.removeItem('saas_token');
  setToken(null);
  setUser(null);
}, []);

Login and register write both localStorage and state in the same breath. Logout tries the server first (revoking the token server-side is polite) but clears locally regardless. The session dies on the client even if the server call fails, because a logout that depends on a healthy network is a logout that fails exactly when the user needs it most.

On mount, the context restores the session: read the key, call GET /auth/me, and if that fails, remove the key and settle into logged-out. One code path for "returning visitor" and "dead token".

Owner three: nobody. That is the point. No component reads localStorage directly. No page checks the token itself. Every component goes through useAuth(), which exposes exactly six things: user, token, loading, login, register, logout. And useAuth throws if you call it outside the provider, so forgetting the wrapper fails loudly in development instead of silently shipping undefined auth everywhere:

export function useAuth() {
  const ctx = useContext(AuthContext);
  if (!ctx) throw new Error('useAuth must be used within an AuthProvider');
  return ctx;
}

The payoff: if I ever move from localStorage to httpOnly cookies, the change surface is two files, client.js and AuthContext.jsx. Every consumer keeps working because they never knew where the token lived. Ownership is a contract: one name, two modules, and a public API of six values. Everything else just asks.

This is the auth layer of the starter kit I maintain and sell. The full thing, with the Sanctum backend and this exact frontend, is here: Laravel + React SaaS Starter Kit

My demo build is a config I never commit: the temporary vite setup behind the public preview

Kamran Khan — Wed, 21 Oct 2026 04:15:07 +0000

My SaaS starter kit has two builds. One ships to customers. One powers the public demo. They come from the same source tree, but the demo gets its own vite config, and that config has a comment at the top that says, in effect: temporary, demo only, do not commit.

Here it is, the whole thing:

// TEMPORARY build config for the /demo/ GitHub Pages deploy ONLY.
// Externalizes vendor deps (loaded via importmap from esm.sh) so the app
// bundle stays small. NOT for the shipped product — do not commit.
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  base: '/laravel-react-saas-starter-kit/demo/',
  build: {
    outDir: 'dist-demo',
    rollupOptions: {
      external: ['react', 'react/jsx-runtime', 'react-dom',
                 'react-dom/client', 'react-router-dom', 'axios'],
    },
  },
});

Twenty lines. Three decisions worth stealing.

Decision one: the demo build externalizes vendor dependencies. The demo runs on GitHub Pages with base set to the /demo/ subpath, and react, react-dom, react-router-dom and axios are declared external so they load from an import map (esm.sh) instead of being bundled. The app bundle stays small, which matters when your demo is the first impression and the visitor is on a phone connection. The shipped product does none of this; its normal vite config bundles everything the usual way.

Decision two: the demo config lives next to the real one, not inside it. I did not add if (demo) branches to the shipped vite.config.js. Demo needs are not product needs. The day a demo special-case lands in the shipped config, every future customer build pays the tax: extra conditionals to read, extra ways for a demo flag to leak into production output. Two configs, one of them labelled disposable, keeps the product's build pipeline honest.

Decision three: the config is honest about being disposable. The comment says do not commit it. In practice that means the demo deploy is a local, manual step: build with this config, push dist-demo to the /demo/ path, and the repo's tracked build config stays the clean one. Nobody inherits a mysterious demo hack six months later and wonders whether it is load-bearing.

How does the app know it is the demo? A build-time flag. The axios client checks it:

const client = isDemoMode() ? createDemoClient() : axios.create({
  baseURL: `${import.meta.env.VITE_API_URL || 'http://localhost:8000'}/api`,
  headers: { Accept: 'application/json' },
});

VITE_DEMO_MODE=true swaps the real Laravel API for an in-memory mock that mirrors the endpoints and response shapes, so the preview is fully clickable with no backend. The product default is the real API. One seam, one flag, and the demo config never touches a line of application code.

The pattern generalises: anything you build to sell the thing should be physically separated from the thing itself. Demos rot faster than products. When the demo is a labelled, temporary config rather than conditionals woven through your build, deleting it later is a one-line act of hygiene instead of archaeology.

I write about real patterns from client work and the starter kit I sell. If the behind-the-scenes of a $19 boilerplate interests you, the whole thing is here: Laravel + React SaaS Starter Kit