In this post on Astro Turbolinks, we first take a look at what Turbolinks are and why they exist. We then see how you can add Turbolinks to your Astro JS site for fast navigation. You will see it is more or less just a case of adding a package and a couple of lines of config.
When a visitor clicks an internal link on your site (a link to another page on the same site), the browser follows the link and requests the new page. If the site is not too optimised, there might be a flash of white content as the browser waits for the new page. This is known as a full page refresh. Turbolinks offers an alternative model.
With Turbolink, when the visitor clicks an internal link, instead of following the link, Turbolinks intercepts it. It then uses something called an XMLHttpRequest to get the page from the server. This is a method which allows the browser to fetch the new page without doing a full page refresh. The smart bit comes when Turbolinks receives the response. It looks for differences between the previous page and the new one. Next, it swaps content which is different on the new page, but keeps identical content. As a final step Turbolinks changes the browser’s url so that it matches the new rendered page.
For users on a slow connection, Turbolinks offers a user experience enhancement. By avoiding the full page refresh, the change will look smoother, allowing the user to carry on with what they were doing in the case only a small part of the page changes.
Much of the Turbolinks functionality works automatically behind the scenes. Essentially to add it to your Astro JS site, you just need to install a single package and update config. You can even automate that setup! We will look at a couple of use cases. First, adding Turbolinks to a new Astro site, using automated setup. Then we see how you might add it to an existing Astro project using manual, albeit fairly simple, setup.
During this setup process you can choose from a list of different site types including Generic and Blog as well as Minimal. It’s not too much bother fully to customise your project later. With that in mind, just choose whichever option sounds closest to what you are doing and take it from there. We disable Astro telemetry here, skip that line if you want to keep it enabled.
In the following line we add Turbolinks. This will prompt you automatically to install the
@astrojs/turbolinks package and add configuration to
astro.config.mjs. Answer yes
to perform these steps automatically. In that same line we are adding setup for Svelte and React.
Delete these if you do not need them. Alternatively, introduce others you might want by adding
preact to the command.
That’s it! Jump to the test section to check it’s all working.
You can also run
astro add on an existing project, but might choose
to do the setup manually instead. As a first step, install the
Then you just need to update
Here we import the package we just installed, then add it to any existing
With Astro already being so fast, you might not be able to perceive Turbolinks is working on your dev server. One way to check is to open up the Network tab in your browser developer tools.
We have Firefox developer tools open here. You can see an
@astrojs_turbolinks_client entry in the File column of the selected line highlighted here. If you are using
Chrome Dev tools, open the Network tab and look in the first (Name) column.
We have taken a look at adding Turbolinks to a new or existing Astro site in this post. In particular, we looked at:
- what Turbolinks is and why you might us it,
how you can add Turbolinks to your Astro JS site using
- how you can manually add and setup Turbolink links to you Astro site.
If you are creating a new blog site, take a look at the Astro Blog Markdown starter on GitHub , which uses Turbolinks. Also take a look if you want to see the configuration in a full project. You can also open the project up in Stackblitz .
I hope you found this article useful and am keen to hear how you will the starter on your own projects as well as possible improvements.
- Turbolinks is a project which optimises page load for internal pages on your site. Typically when a user clicks an internal link, the browser follows the link and fetches the new page. In the meantime there is a flash of a white screen as the new page loads. Turbolinks intercepts navigation to internal pages. It changes the browser URL to the new page but keeps the original page. It fetches the content for the new page and does a comparison. Finally it swaps out any different content, but keeps content the new and old pages have in common. This avoids the blank screen seen in a full page refresh. On top, when only a small element of the page changes, the site visitor can just carry on while Turbolinks works its magic.
- Since Turbolinks does most of its work automatically, behind the scenes, and needs very little configuration, it is a good match for Astro. Fortunately it does work with Astro and like the original project, you only need a small amount of configuration to get it up and running.
- The easiest way to add Turbolinks to a new Astro project, is to run pnpm astro add turbolinks in the Terminal. This will prompt you to install a package automatically as well as update the project configuration. If you prefer to do things manually, for example if you have an existing Astro project, you can too! First install the package: `pnpm add -D @astrojs/turbolinks`. Then, finally import this package to you astro.config.mjs file, then add it to the integrations array.
Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please consider supporting me through Buy me a Coffee.
Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on Twitter and also askRodney on Telegram . Also, see further ways to get in touch with Rodney Lab. I post regularly on Astro as well as SvelteKit. Also subscribe to the newsletter to keep up-to-date with our latest projects.