Reduce bundle size: extract getSession and improve tree-shaking #1334

New Issue

GiteaMirror · 2026-03-13T08:33:34-05:00

GiteaMirror commented

2026-03-13 08:33:34 -05:00

Originally created by @paol-imi on GitHub (Jun 9, 2025).

Originally assigned to: @himself65 on GitHub.

Is this suited for github?

Yes, this is suited for github

We use better-auth in a serverless context. The library adds ~500 kB to our bundle, which directly impacts cold start time. Ideally, the library would allow better tree-shaking and more granular control on which API get used or not.

Describe the solution you'd like

An initial smaller step could be to extract getSession into a standalone utility. This would allow patterns like lazy-loading the library inside signin/signout routes only when needed, while keeping the rest of the app lightweight by using getSession directly.

Describe alternatives you've considered

Manually copying just the needed parts of getSession
Replacing the library in cold-path endpoints

Additional context

No response

Originally created by @paol-imi on GitHub (Jun 9, 2025). Originally assigned to: @himself65 on GitHub. ### Is this suited for github? - [x] Yes, this is suited for github ### Is your feature request related to a problem? Please describe. We use better-auth in a serverless context. The library adds ~500 kB to our bundle, which directly impacts cold start time. Ideally, the library would allow better tree-shaking and more granular control on which API get used or not. ### Describe the solution you'd like An initial smaller step could be to extract `getSession` into a standalone utility. This would allow patterns like lazy-loading the library inside signin/signout routes only when needed, while keeping the rest of the app lightweight by using getSession directly. ### Describe alternatives you've considered - Manually copying just the needed parts of getSession - Replacing the library in cold-path endpoints ### Additional context _No response_

GiteaMirror commented

2026-03-13 08:33:37 -05:00

@mlafeldt commented on GitHub (Oct 21, 2025):

I'm currently evaluating Better Auth as a Clerk replacement, and I also noticed that it's not made for serverless environments.

Using it in my Astro project (deployed to Cloudflare Pages) adds a whopping 1400K to the bundle.

Before (using Clerk):

...
   222.7K  dist/_worker.js/chunks/astro/server_BeLhyc_3.mjs
   241.1K  dist/_worker.js/chunks/index_LICAQjiJ.mjs
   510.9K  dist/_worker.js/chunks/_@astro-renderers_DgFsZQUB.mjs
  2075.3K  total (57 modules)

After (using Better Auth):

...
   255.3K  dist/_worker.js/_astro-internal_middleware.mjs
   545.3K  dist/_worker.js/chunks/_@astro-renderers_CNzeWT4e.mjs
  1396.8K  dist/_worker.js/chunks/auth_4uEdegud.mjs
  3503.7K  total (55 modules)

One big optimization I was able to implement is to stub out Kysley. Turns out Better Auth will still pull it in even when using Drizzle. With the Kysley hack/stub:

...
   255.3K  dist/_worker.js/_astro-internal_middleware.mjs
   545.3K  dist/_worker.js/chunks/_@astro-renderers_CNzeWT4e.mjs
   889.9K  dist/_worker.js/chunks/auth_O5bSokMB.mjs
  2996.8K  total (55 modules)

Here's the Vite plugin that does the stubbing:

// Stub out kysely to reduce bundle size (better-auth imports it even with drizzle adapter)
function stubKysely(): Plugin {
  return {
    name: 'stub-kysely',
    enforce: 'pre',
    resolveId(id) {
      if (id === 'kysely') {
        return '\0kysely-stub'
      }
    },
    load(id) {
      if (id === '\0kysely-stub') {
        return `
          export function getKyselyDatabaseType() { return null; }
          export class Kysely {}
          export class SqliteDialect {}
          export class MysqlDialect {}
          export class PostgresDialect {}
          export class MssqlDialect {}
          export class CompiledQuery {}
          export class DefaultQueryCompiler {}
          export const sql = {}
          export const DEFAULT_MIGRATION_TABLE = ''
          export const DEFAULT_MIGRATION_LOCK_TABLE = ''
        `
      }
    },
  }
}

1 MB still feels like a lot, esp. considering that all the rest of the serverless project is 2 MB.

I don't know if there's any effective tree shaking happening right now, but basically everything (including social providers I don't use) gets deployed as part of the bundle.

@mlafeldt commented on GitHub (Oct 21, 2025): I'm currently evaluating Better Auth as a Clerk replacement, and I also noticed that it's not made for serverless environments. Using it in my Astro project (deployed to Cloudflare Pages) adds a whopping **1400K** to the bundle. Before (using Clerk): ``` ... 222.7K dist/_worker.js/chunks/astro/server_BeLhyc_3.mjs 241.1K dist/_worker.js/chunks/index_LICAQjiJ.mjs 510.9K dist/_worker.js/chunks/_@astro-renderers_DgFsZQUB.mjs 2075.3K total (57 modules) ``` After (using Better Auth): ``` ... 255.3K dist/_worker.js/_astro-internal_middleware.mjs 545.3K dist/_worker.js/chunks/_@astro-renderers_CNzeWT4e.mjs 1396.8K dist/_worker.js/chunks/auth_4uEdegud.mjs 3503.7K total (55 modules) ``` One big optimization I was able to implement is to stub out Kysley. Turns out Better Auth will still pull it in even when using Drizzle. With the Kysley hack/stub: ``` ... 255.3K dist/_worker.js/_astro-internal_middleware.mjs 545.3K dist/_worker.js/chunks/_@astro-renderers_CNzeWT4e.mjs 889.9K dist/_worker.js/chunks/auth_O5bSokMB.mjs 2996.8K total (55 modules) ``` Here's the Vite plugin that does the stubbing: <details> ```ts // Stub out kysely to reduce bundle size (better-auth imports it even with drizzle adapter) function stubKysely(): Plugin { return { name: 'stub-kysely', enforce: 'pre', resolveId(id) { if (id === 'kysely') { return '\0kysely-stub' } }, load(id) { if (id === '\0kysely-stub') { return ` export function getKyselyDatabaseType() { return null; } export class Kysely {} export class SqliteDialect {} export class MysqlDialect {} export class PostgresDialect {} export class MssqlDialect {} export class CompiledQuery {} export class DefaultQueryCompiler {} export const sql = {} export const DEFAULT_MIGRATION_TABLE = '' export const DEFAULT_MIGRATION_LOCK_TABLE = '' ` } }, } } ``` </details> 1 MB still feels like a lot, esp. considering that all the rest of the serverless project is 2 MB. I don't know if there's any effective tree shaking happening right now, but basically everything (including social providers I don't use) gets deployed as part of the bundle.

GiteaMirror commented

2026-03-13 08:33:37 -05:00

@paol-imi commented on GitHub (Oct 21, 2025):

To the best of my knowledge, the library is currently quite difficult to tree-shake largely because the codebase has tightly coupled components – everything from the database adapter (Kysely) to HTTP API endpoints is bundled together. This makes sense as a result of for the "batteries-included" approach the team has been taking, prioritizing feature completeness and out-of-the-box functionality, which was clearly key to the library's rapid adoption and early success.

It's clear there's room for improvement in terms of internal codebase design. A full refactor to make everything properly modular would require substantial design work and time, and I imagine it's hard to prioritize that in the near future given the project's growth trajectory. However, an initial roadmap that could have low impact on the current codebase would be to carefully externalize specific utilities and rely on lazy loading patterns.

For example, if getSession were extracted as a standalone utility, we could do something like:

// router.ts
export const router = createRouter({
  auth: lazy(() => import("./router/auth")),
  example: lazy(() => import("./router/example"))
});

// routes/example.ts
import { getSession } from "better-auth";

export const handler = (req: Request) => {
  const session = getSession(req);
  if (!session) throw new Error("401 Unauthorized");
  // From here we can access the session...
};

This way, the heavy auth logic only loads in routes that actually need it (signin/signout), while most of the app stays lightweight. The getSession import would be tree-shakeable with almost no footprint on bundle size.

@mlafeldt's findings about Kysely being pulled in even when using Drizzle is a perfect example of how the tight coupling is affecting bundle size in practice. Would love to see even incremental improvements here.

@paol-imi commented on GitHub (Oct 21, 2025): To the best of my knowledge, the library is currently quite difficult to tree-shake largely because the codebase has tightly coupled components – everything from the database adapter (Kysely) to HTTP API endpoints is bundled together. This makes sense as a result of for the "batteries-included" approach the team has been taking, prioritizing feature completeness and out-of-the-box functionality, which was clearly key to the library's rapid adoption and early success. It's clear there's room for improvement in terms of internal codebase design. A full refactor to make everything properly modular would require substantial design work and time, and I imagine it's hard to prioritize that in the near future given the project's growth trajectory. However, an **initial roadmap** that could have **low impact** on the current codebase would be to carefully externalize specific utilities and rely on lazy loading patterns. For example, if getSession were extracted as a standalone utility, we could do something like: ```ts // router.ts export const router = createRouter({ auth: lazy(() => import("./router/auth")), example: lazy(() => import("./router/example")) }); ``` ```ts // routes/example.ts import { getSession } from "better-auth"; export const handler = (req: Request) => { const session = getSession(req); if (!session) throw new Error("401 Unauthorized"); // From here we can access the session... }; ``` This way, the heavy auth logic only loads in routes that actually need it (signin/signout), while most of the app stays lightweight. The getSession import would be tree-shakeable with almost no footprint on bundle size. @mlafeldt's findings about Kysely being pulled in even when using Drizzle is a perfect example of how the tight coupling is affecting bundle size in practice. Would love to see even incremental improvements here.

GiteaMirror commented

2026-03-13 08:33:37 -05:00

@paol-imi commented on GitHub (Oct 21, 2025):

@Kinfe123 should we move this to a discussion?

@paol-imi commented on GitHub (Oct 21, 2025): @Kinfe123 should we move this to a discussion?

GiteaMirror commented

2026-03-13 08:33:38 -05:00

@Bekacru commented on GitHub (Oct 21, 2025):

This should be addressed on 1.4 release. We're working on having a minimal import for those who aren't using kysley directly. And we're refactoring out passkey and other plugins to make them a separate package.

In the meantime I suggest importing plugins from their designated path instead of better-auth/plugins (like for two factor from better-auth/plugins/two-factor) to avoid importing all plugins we export

@Bekacru commented on GitHub (Oct 21, 2025): This should be addressed on 1.4 release. We're working on having a minimal import for those who aren't using kysley directly. And we're refactoring out `passkey` and other plugins to make them a separate package. In the meantime I suggest importing plugins from their designated path instead of `better-auth/plugins` (like for two factor from `better-auth/plugins/two-factor`) to avoid importing all plugins we export

GiteaMirror commented

2026-03-13 08:33:38 -05:00

@mlafeldt commented on GitHub (Oct 21, 2025):

This should be addressed on 1.4 release. We're working on having a minimal import for those who aren't using kysley directly. And we're refactoring out passkey and other plugins to make them a separate package.

That's great news! Looking forward to 1.4 then.

In the meantime I suggest importing plugins from their designated path instead of better-auth/plugins (like for two factor from better-auth/plugins/two-factor) to avoid importing all plugins we export

I don't use any plugins right now, so I probably can't benefit from this. I measured the bundle sizes with emailAndPassword only.

@mlafeldt commented on GitHub (Oct 21, 2025): > This should be addressed on 1.4 release. We're working on having a minimal import for those who aren't using kysley directly. And we're refactoring out `passkey` and other plugins to make them a separate package. That's great news! Looking forward to 1.4 then. > In the meantime I suggest importing plugins from their designated path instead of `better-auth/plugins` (like for two factor from `better-auth/plugins/two-factor`) to avoid importing all plugins we export I don't use any plugins right now, so I probably can't benefit from this. I measured the bundle sizes with `emailAndPassword` only.

GiteaMirror commented

2026-03-13 08:33:39 -05:00

@himself65 commented on GitHub (Oct 21, 2025):

I will handle this

@himself65 commented on GitHub (Oct 21, 2025): I will handle this

GiteaMirror commented

2026-03-13 08:33:39 -05:00

@sabaturgay commented on GitHub (Nov 1, 2025):

Thanks for this excellent library!

I wanted to provide additional context regarding bundle size. While reviewing the esbuild meta file, I noticed that zod/locales alone adds 173kb to the bundle. It would be great if this could either be removed entirely or made optional for those who need it.

@sabaturgay commented on GitHub (Nov 1, 2025): Thanks for this excellent library! I wanted to provide additional context regarding bundle size. While reviewing the esbuild meta file, I noticed that `zod/locales` alone adds **173kb** to the bundle. It would be great if this could either be removed entirely or made optional for those who need it.

GiteaMirror commented

2026-03-13 08:33:40 -05:00

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025):

Based on your feedback, a good next step would be to implement a twofold approach:

Decouple getSession so that it can be imported separately (or lazy-loaded) from the rest of the library. This would let you include only what you need in cold-path endpoints and avoid loading unused functionality [1].
Investigate making the zod locales dependency optional or even removable. Since zod/locales is adding a significant chunk (~173 kB) to your bundle, you might either configure your bundler to ignore it (for instance, via a plugin or alias) or propose a change to better-auth so that these locales are loaded only when needed [1].

I recommend opening a pull request with these improvements or testing a fork with these changes to verify the impact on your cold start times. This approach should help you reduce the bundle size noticeably while maintaining functionality where needed [1].

Diagram • Discord • GitHub

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025): Based on your feedback, a good next step would be to implement a twofold approach: 1. Decouple getSession so that it can be imported separately (or lazy-loaded) from the rest of the library. This would let you include only what you need in cold-path endpoints and avoid loading unused functionality [[1]](https://github.com/better-auth/better-auth/issues/2964). 2. Investigate making the zod locales dependency optional or even removable. Since zod/locales is adding a significant chunk (~173 kB) to your bundle, you might either configure your bundler to ignore it (for instance, via a plugin or alias) or propose a change to better-auth so that these locales are loaded only when needed [[1]](https://github.com/better-auth/better-auth/issues/2964). I recommend opening a pull request with these improvements or testing a fork with these changes to verify the impact on your cold start times. This approach should help you reduce the bundle size noticeably while maintaining functionality where needed [[1]](https://github.com/better-auth/better-auth/issues/2964).  [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)

GiteaMirror commented

2026-03-13 08:33:40 -05:00

@mlafeldt commented on GitHub (Nov 1, 2025):

Is this AI slop supposed to add anything to the conversation? 😐

@mlafeldt commented on GitHub (Nov 1, 2025): Is this AI slop supposed to add anything to the conversation? 😐

GiteaMirror commented

2026-03-13 08:33:41 -05:00

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025):

Based on the request, the next step is to extract getSession into its own module so that it can be lazy-loaded in sign‑in/sign‑out routes rather than bundled into the main application code. This approach can allow your bundler to remove unused API parts and reduce cold start overhead.

To troubleshoot, first verify that your bundler (for example, Webpack or Rollup) is configured for optimal tree‑shaking (such as setting sideEffects: false if applicable). Then refactor getSession as a standalone utility and test dynamic imports to ensure that only the required code is loaded when needed [1].

If tree‑shaking still struggles, consider checking if any other side effects in the library prevent proper elimination of unused code. This iterative process should help you isolate and minimize the bundle size for better performance in a serverless context.

Diagram • Discord • GitHub

@better-auth-agent[bot] commented on GitHub (Nov 1, 2025): Based on the request, the next step is to extract getSession into its own module so that it can be lazy-loaded in sign‑in/sign‑out routes rather than bundled into the main application code. This approach can allow your bundler to remove unused API parts and reduce cold start overhead. To troubleshoot, first verify that your bundler (for example, Webpack or Rollup) is configured for optimal tree‑shaking (such as setting sideEffects: false if applicable). Then refactor getSession as a standalone utility and test dynamic imports to ensure that only the required code is loaded when needed [[1]](https://github.com/better-auth/better-auth/issues/2964). If tree‑shaking still struggles, consider checking if any other side effects in the library prevent proper elimination of unused code. This iterative process should help you isolate and minimize the bundle size for better performance in a serverless context.  [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)

GiteaMirror commented

2026-03-13 08:33:43 -05:00

@dosubot[bot] commented on GitHub (Jan 31, 2026):

Hi, @paol-imi. I'm Dosu, and I'm helping the better-auth team manage their backlog and am marking this issue as stale.

Issue Summary:

You raised concerns about better-auth's large bundle size (~500 kB), affecting serverless cold start times.
You suggested extracting getSession as a standalone utility to improve tree-shaking and enable lazy loading.
Other users confirmed even larger bundle sizes (up to 1.4 MB) and shared workarounds like stubbing out Kysely.
The maintainer mentioned upcoming improvements in version 1.4, including minimal imports and plugin refactoring.
The discussion also touched on modularization and making dependencies like zod/locales optional to optimize bundle size.

Next Steps:

Please let me know if this issue is still relevant with the latest version of better-auth by commenting below.
If I don’t hear back within 7 days, I will automatically close this issue to keep the backlog manageable.

Thanks for your understanding and contribution!

@dosubot[bot] commented on GitHub (Jan 31, 2026): Hi, @paol-imi. I'm [Dosu](https://dosu.dev), and I'm helping the better-auth team manage their backlog and am marking this issue as stale. **Issue Summary:** - You raised concerns about better-auth's large bundle size (~500 kB), affecting serverless cold start times. - You suggested extracting `getSession` as a standalone utility to improve tree-shaking and enable lazy loading. - Other users confirmed even larger bundle sizes (up to 1.4 MB) and shared workarounds like stubbing out Kysely. - The maintainer mentioned upcoming improvements in version 1.4, including minimal imports and plugin refactoring. - The discussion also touched on modularization and making dependencies like zod/locales optional to optimize bundle size. **Next Steps:** - Please let me know if this issue is still relevant with the latest version of better-auth by commenting below. - If I don’t hear back within 7 days, I will automatically close this issue to keep the backlog manageable. Thanks for your understanding and contribution!

GiteaMirror commented

2026-03-13 08:33:43 -05:00

@mlafeldt commented on GitHub (Feb 7, 2026):

I will handle this

Closing as not planned is the opposite of handling this.

@mlafeldt commented on GitHub (Feb 7, 2026): > I will handle this Closing as not planned is the opposite of handling this.

GiteaMirror commented

2026-03-13 08:33:44 -05:00

@himself65 commented on GitHub (Feb 7, 2026):

I will handle this

Closing as not planned is the opposite of handling this.

This would take a lot of work. I'm going to move the code to the correct files

@himself65 commented on GitHub (Feb 7, 2026): > > I will handle this > > Closing as not planned is the opposite of handling this. This would take a lot of work. I'm going to move the code to the correct files

GiteaMirror referenced this issue

2026-04-13 03:51:40 -05:00

[GH-ISSUE #1334] SimpleLogin OIDC provider #8697

GiteaMirror referenced this issue

2026-04-15 15:26:37 -05:00

[GH-ISSUE #1334] SimpleLogin OIDC provider #17328

GiteaMirror referenced this issue

2026-04-17 16:24:25 -05:00

[GH-ISSUE #1334] SimpleLogin OIDC provider #26020

Sign in to join this conversation.

Branches Tags

2026-05-22/chore/adopt-agents-md

2026-05-22/refactor/string-case-utils

dependabot/npm_and_yarn/uuid-14.0.0

dependabot/npm_and_yarn/turbo-2.9.14

changeset-release/main

main

2026-05-14/fix/passkey-verify-error-and-claim

dependabot/npm_and_yarn/samlify-2.13.0

dependabot/npm_and_yarn/ws-8.20.1

changeset-release/next

dependabot/npm_and_yarn/demo/electron/demo-minor-patch-519ef7475f

dependabot/github_actions/github-actions-98f3470200

client-assertions-main

2026-05-15/ci/fix-sqlite-abi-mismatch

2026-05-15/fix/organization-team-add-cascade

2026-05-15/fix/parse-set-cookie-value-validation

2026-05-13/feat/captcha-wildcard-endpoints

2026-05-13/ci/stabilize-docker-startup

fix/i18n-before-hook-translation

fix/disable-migration-generate

2026-05-07/fix/admin-set-password-upsert

2026-05-10/fix/cookie-drain-order

2026-05-10/feat/hooks-finally

2026-05-09/fix/cookie-drain-order

2026-05-09/feat/hooks-finally

2026-05-08/feat/register-before-send

fix/stripe/subscription-data-merge

2026-05-01/chore/pnpm-v11-harden

chore/pnpm-v11

2026-04-29/feat/google-include-granted-scopes

2026-04-29/fix/oauth-account-scope-semantics

2026-04-27/fix/nextcookies-idempotent-writes

2026-04-26/fix/harden-proxy-host-validation

2026-04-26/refactor/stripe-callback-signature-cleanup

2026-04-26/fix/stripe-subscription-callback-timing

2026-04-11/fix/sveltekit-app-modules

feat/open-api-zod-contract

feat/oauth-provider-backchannel-logout-next

feat/oauth-idp-initiated-bounce

refactor/sign-in-challenges

2026-04-21/fix/oauth-rfc-input-validation

fix/release-notes-new-packages

fix/two-factor-identity-guard

fix/resource

feat/emailpassword-authorize

2026-04-12/security/dynamic-baseurl-proxy-trust-default

feat/oauth-provider-at-hash-v2

fix/release-grep-fallback

claude/address-review-comments-JhFLr

claude/slack-update-stripe-docs-consistency-8Sc0w

feat/async-auth

fix/two-factor-totp-verified-enrollment

feat/plugin-ui

codex/blog-1-6-release-post

2026-04-06/fix/type-any-guards

2026-04-05/chore/downgrade-better-call

2026-04-04/ci/skip-vercel-fork-prs

2026-03-28/ci/add-autofix-ci

chore/release-preview-script

himself65/2026/02/19/role

2026-03-24/fix/update-user-info-on-link

2026-03-20/docs/improve-website

2026-03-20/fix/anonymous-onlinkaccount-expo

2026-02-17/fix/anonymous-link-state

fix/8607-saml-inresponseto

fix/8549-scim-patch-noop

v1.4.x

refactor/migration-snapshot-tests

worktree-magic-link-additional-data

chore/migrate-build-to-rollup

worktree-fix-dynamic-baseurl-8447

2026-03-06/chore/public-api-check

fix/close-8156-regression-test

fix/secondary-storage-json-error-handling

himself65/verification-namespace

cursor/issue-8307-validation-79a3

himself65/2026/01/30/error-mdx

v1.4.x-staging

fix/email-otp-user

fix/restrict-full-organization-access-roles

himself65/2026/02/12/count

himself65/2026/02/04/define-plugin

2026-02-04/feat/add-pluralize

cursor/better-auth-js-integration-ec21

cursor/expo-state-mismatch-394c

2026-02-01/fix/org-update-role-sync-members

cursor/issue-7607-investigation-e146

cursor/email-generation-helper-0ff6

himself65/2026/01/21/avoid-spread-operator

himself65/2026/01/14/cli

claude/slack-add-docs-pr-NMvgO

claude/slack-add-advanced-useplural-WHKYL

feat/hooks-pos

feat/2fa-phone

feat/2fa

fix/rotation

fix/username-check

v1.3.x

refactor/organization

feat/multiple-client-ids-social-providers

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/better-auth#1334