In this post on Astro JS non-HTML routes, we see you can create file routes or resource routes in Astro. Astro specialises 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, 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 take 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
customisation). 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 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. Here you can go for our approach using a static site. We can generate the PDF at build time in our file route. Once again every user will get the same newsletter, 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 personalise the factsheet, adding the visitor’s name at the top of the 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 personalised 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 be
src/pages/pdf-resource.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
For 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 customise it for each visitor.
For the SSR equivalent, we do not need the
Response object and can also include the
We also are free to customise the output here for every request.
Here we build the JSON within the file. Again for a static site, we can customise per-build, but
have to go full SSR to customise 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 taken 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 to 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, take a look at the full project code on the Rodney Lab GitHub page
- No, is the short answer! A great example is the manifest.json file which contains info on your sites 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 Generated and customise 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 our of Astro 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