{"id":1529,"date":"2026-08-19T06:35:49","date_gmt":"2026-08-19T06:35:49","guid":{"rendered":"https:\/\/www.projectimmerse.com\/blog\/?p=1529"},"modified":"2026-08-19T06:47:19","modified_gmt":"2026-08-19T06:47:19","slug":"vue-3-async-components-how-to-stop-making-your-users-download-your-entire-app-on-page-load","status":"publish","type":"post","link":"https:\/\/www.projectimmerse.com\/blog\/vue-3-async-components-how-to-stop-making-your-users-download-your-entire-app-on-page-load\/","title":{"rendered":"Vue 3 Async Components: How to Stop Making Your Users Download Your Entire App on Page Load"},"content":{"rendered":"\n
\"Vue<\/a>
Use Vue 3 async components to lazy-load code only when users need it.<\/figcaption><\/figure>\n\n\n\n

Let’s talk about a very specific kind of guilt: the guilt of shipping a JavaScript bundle so big it has its own gravitational pull.<\/p>\n\n\n\n

You know the feeling. You open your dev tools, check the Network tab, and there it is \u2014 a single bundle.js<\/code> file the size of a small documentary, loading in full before your user can even see a “Sign In” button. Somewhere in there is your entire admin dashboard, your rarely-used settings page, and that one chart library you imported for a feature three people use.<\/p>\n\n\n\n

The good news: Vue 3 has a built-in fix for this, and it’s been sitting right there in the docs the whole time, quietly judging your bundle size. It’s called defineAsyncComponent<\/code>, and once you understand it, you’ll wonder why you were ever making users download the whole toy box just to play with one toy.<\/p>\n\n\n\n

By the end of this article, you’ll know exactly how it works, when to use it, when not<\/em> to use it, and you’ll have a working demo you can poke at yourself. I’ve also put a full working example on GitHub, linked at the bottom, so you don’t have to just take my word for any of this.<\/p>\n\n\n\n\n\n\n\n

The Problem: Loading Everything, Using Almost Nothing<\/h2>\n\n\n\n

Here’s the thing about large Vue applications \u2014 they’re large. Shocking, I know. But the issue isn’t really the size, it’s when<\/em> everything gets loaded.<\/p>\n\n\n\n

By default, if you import a component like this:<\/p>\n\n\n

\nimport AdminPanel from '.\/components\/AdminPanel.vue'\n\n<\/pre><\/div>\n\n\n
That component gets bundled into your main JavaScript file and loaded every single time<\/strong>, whether the user is an admin, a regular user, or a bot that wandered in from a search engine and has zero interest in your admin panel.<\/p>\n\n\n\n
Multiply that by every modal, every rarely-visited page, and every “just in case” component, and you’ve got a bundle that takes longer to load than it takes to make a decent cup of coffee.<\/p>\n\n\n\n
The Fix: defineAsyncComponent<\/code><\/h2>\n\n\n\n
Vue’s answer to this is refreshingly simple. Instead of importing a component up front, you tell Vue: “only go get this thing when it’s actually needed.”<\/p>\n\n\n
\nimport { defineAsyncComponent } from 'vue'\n\nconst AsyncComp = defineAsyncComponent(() => {\n  return new Promise((resolve, reject) => {\n    \/\/ go fetch the component from wherever\n    resolve(\/* the loaded component *\/)\n  })\n})\n\n<\/pre><\/div>\n\n\n
defineAsyncComponent<\/code> takes a loader function<\/strong> that returns a Promise. When the Promise resolves, Vue swaps in the real component. When it rejects, Vue can show you a fallback instead of just quietly dying inside.<\/p>\n\n\n\n
In practice, you’ll almost always pair this with a dynamic import()<\/code>, especially if you’re using Vite or webpack (which, statistically, you probably are):<\/p>\n\n\n
\nconst AsyncComp = defineAsyncComponent(() =>\n  import('.\/components\/MyComponent.vue')\n)\n\n<\/pre><\/div>\n\n\n
That import()<\/code> syntax isn’t just convenient \u2014 bundlers actually recognize it as a code-splitting point<\/strong>. Translation: your bundler will automatically chop that component out into its own separate file, and only load it when it’s needed. You don’t have to configure anything extra. It just happens. It’s the closest thing to free performance you’ll get in this industry.<\/p>\n\n\n\n
Using It Like a Normal Component<\/h2>\n\n\n\n
Here’s the part that makes this genuinely pleasant to use: once you’ve wrapped a component in defineAsyncComponent<\/code>, you use it exactly like a regular component<\/strong>. Same props, same slots, same everything.<\/p>\n\n\n
\n&lt;script setup>\nimport { defineAsyncComponent } from 'vue'\n\nconst AdminPage = defineAsyncComponent(() =>\n  import('.\/components\/AdminPageComponent.vue')\n)\n&lt;\/script>\n\n&lt;template>\n  &lt;AdminPage \/>\n&lt;\/template>\n\n<\/pre><\/div>\n\n\n
Vue quietly takes care of the “wait for it to load” logic behind the scenes. Your template doesn’t need to know or care that this component technically doesn’t exist yet.<\/p>\n\n\n\n
You can also register async components globally, if you’re the type of developer who likes making sweeping architectural decisions from a single file:<\/p>\n\n\n
\napp.component('MyComponent', defineAsyncComponent(() =>\n  import('.\/components\/MyComponent.vue')\n))\n\n<\/pre><\/div>\n\n\n
Handling Loading and Error States (Because Networks Are Liars)<\/h2>\n\n\n\n
Here’s where a lot of tutorials stop, and it’s a shame, because this is the part that actually matters in production. Networks fail. Servers hiccup. Someone’s on a train going through a tunnel. You need to handle that.<\/p>\n\n\n\n
defineAsyncComponent<\/code> accepts an options object for exactly this:<\/p>\n\n\n
\nconst AsyncComp = defineAsyncComponent({\n  loader: () => import('.\/components\/MyComponent.vue'),\n  loadingComponent: LoadingSpinner,\n  errorComponent: ErrorMessage,\n  delay: 200,\n  timeout: 3000\n})\n\n<\/pre><\/div>\n\n\n