In this post on Astro JS non-HTML routes, we see you can create file routes or resource routes in Astro. Astro specializes in delivering content sites and doing so quickly. However, that content does not have to be just HTML pages. In fact, we see a couple of examples of Astro non-HTML routes. In the first example, we generate and serve a PDF file from an API route. Meanwhile, in the second example, we create some JSON data (again from a resource route). You could extend this to create a JSON API. Although our examples focus on static Astro sites, we see the techniques can be adapted to work on Astro SSR sites too. On SSR, you can push the boat out, responding to Webhooks as well as generating next-gen images or even creating social sharing images for your sites’ HTML pages.
If truth be told, there is not much to adding a non-HTML route to your Astro site. So instead of building a project from scratch, we will have a look at some example code. Hope that works for you! There is a repo with the complete code if you do want to see the entire picture. You can find a link further down the page for this.
The idea, then, is to be able to link the resources from any HTML code on the site. Here, we put
the links on the home page. Note there are other solutions which might work better depending on
your starting point or use case. Let’s say, for example, you have created a factsheet. You
will serve the same factsheet to anyone who visits the site and clicks the link (no
customization). Here, you could just place the PDF file for the factsheet in the
public folder of your project. In fact, that folder is for anything which does not need processing by
Vite. You could then link
public/factsheet.pdf with an href
Let’s take it up a notch. You still have your factsheet, however, you now want to pull in the latest available data each time you build your app as a static Astro site (the default). The factsheet might pull in data from external APIs, which change from time-to-time. We can generate the PDF at build time in our file route. Once again, every user will get the same factsheet, just you save yourself having to update it manually each time the input data changes.
hrefs look similar to the
public case, though we will source the data differently, generating it in the non-HTML resource route:
If you want to go to town and have an SSR Astro site, you can opt for a similar approach, not too different from what we do here. In this case, you could even personalize, the factsheet, adding the visitor’s name at the top of it. We will see only a small couple of changes are needed to generate the PDF on an SSR site (compared to a static one). In reality, the biggest difference is that you need a form or some other mechanism for collection user personalized data.
To create a non-HTML route in Astro for a static site, you add a new file in
src/pages. Similar to file-based routing for HTML pages, the path will mirror the
href you access the file with. The only difference is that you will add
.ts on the end. So in our snippet above, where the
/pdf-resource.pdf our full path for the resource route will
src/pages/pdf-resource.pdf.ts (we will use TypeScript).
Here’s the file:
We use the
pdfjs package here to generate the PDF for us. It just
has dummy content in our case. You might generate it from scratch, or compose it from other PDFs
in your real-world app. See more on
pdfjs usage in the docs . The most important part is the output we return in line
a static site, aim to return an object with a
body field, which is
a string. For SSR, you can return a
Response object instead and
even stream HTML. We use
binary encoding here, which makes sure
Astro encodes PDFs including images (for example) correctly — thanks to @altano for tip here .
Remember, building a static site, this file will only change when you rebuild the site. This is fine if you do not need to customize it for each visitor.
For the SSR equivalent, we do not need the
Response object and can also include the
We are also free to customize the output here for every request.
Here we build the JSON within the file. Again for a static site, we can customize per-build, but
have to go full SSR to customize per-request. Like for the PDF route, if we do go SSR, we can drop
.json extension (going for
json-resource.ts instead). Naturally, we can also update the
too, going for
In this Astro JS non-HTML routes post, we have had a look at serving files or resources from API routes. In particular, we saw:
- how to serve PDFs and JSON data from static file routes,
- an example generating a PDF resource in an SSR API route,
- when you can avoid these techniques and go for something simpler!
Hope you have found this post useful! As always, there are a lot of ways in which you can level up. You can adapt the code to generate a CSV file on your static or SSR Astro site. You could explore pdfjs and generate a full-featured PDF for your app. If you want to go next-level, consider adding a Webhook listener, for example, which listens for a Webhook from one service and triggers a Webhook on another (like rebuilding your static Astro site)! You could also generate Open Graph social sharing images. Whatever you opt for, have a look at the full project code on the Rodney Lab GitHub page . I am keen to hear how you will the starter on your own projects as well as possible improvements.
- No, is the short answer! A great example is the manifest.json file which contains info on your site’s favicon and other data used in Progressive Web Apps. Typically, this file will not change often and does not need processing by Vite (Astro’s bundler). You can just place the manifest.json file in the `public` folder of your project. If you wanted to serve a more dynamic JSON file. Let’s say you need to pull in fresh data on each build to form the JSON file. Here you might as well make use of Vite and create a resource route. We have seen this is not too difficult to do. You could even make the site Server-Side Rendered and customize the JSON data for each visitor, pulling in real-time data.
- Astro is great for content sites, and it is super common to serve PDFs on content sites. So we are in luck that you can create a PDF on a file route in Astro. We saw an example using pdfjs. But you might also consider pdfkit or even React PDF Renderer. Whatever you opt for, bear in mind if you go for creating a static Astro site, the content will only be refreshed each time you rebuild your site. This will work just fine for a lot of use cases. If you need something more dynamic though, pull SSR out of the Astro toolbox!
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.
Just dropped a new post about using file routes or resource routes in 🚀 Astro.— Rodney (@askRodney) August 24, 2022
We see a JSON example as well as the PDF and also touch on SSR and alternatives, though you might try Webhooks too.
Hope you find it useful!
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.