Astro UserAgent is a simple helper for parsing user-agent header strings for browser matching inside your Astro Pages / API routes, when using SSR Mode
Note Due to the nature of Astro being an SSG by trade, This package only works when used with astro in SSR Mode.
First, install the astro-useragent package using your package manager. (If you aren’t sure which package manager you’re using, run the first command.)
Using PNPM
pnpm install astro-useragentUsing NPM
npm install astro-useragentUsing Yarn
yarn add astro-useragentTo get started, enable SSR features in development mode with the output: server configuration option:
import { defineConfig } from 'astro/config';
export default defineConfig({
output: 'server'
});Note For more info about SSR mode, please refer to the official docs.
To parse a user-agent string inside any of your top level Astro pages, import useUserAgent and then use it inside the frontmatter section:
---
import { useUserAgent } from "astro-useragent";
const uaString = Astro.request.headers.get("user-agent");
const { source, isMobile } = useUserAgent(uaString);
---
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My Astro website</title>
</head>
<body>
<p>Source: {source}</p>
{isMobile ? <p>I'm on mobile</p> : <p>I'm on desktop</p>}
</body>
</html>Note Read more about Astro request headers here: Astro Docs
useUserAgent can also be used inside your API routes, to perform some logic based on the client user-agent.
In the example below, an API route is used to redirect a user to a different mobile page when he is using a mobile client, otherwise it serves the normal content.
import type { APIContext } from 'astro';
import { useUserAgent } from 'astro-useragent';
export async function get({ request }: APIContext) {
const uaString = request.headers.get('user-agent');
const { isMobile } = useUserAgent(uaString);
if (isMobile) {
return Response.redirect('mobile.mysite.com', 307);
}
const greetings = {
message: 'hello from astro API'
};
return new Response(JSON.stringify(greetings), {
status: 200
});
}Note Read more about Astro API routes here: Astro Docs
We have also setup an example repository available here: example-useragent
The parsed UserAgent object will have the following interface:
export interface UserAgent {
readonly source: string; // original user agent string.
readonly deviceType: string | null;
readonly deviceVendor: string | null;
readonly os: string;
readonly osVersion: number;
readonly browser: string;
readonly browserVersion: number;
readonly engine: string;
readonly engineVersion: number;
readonly isIphone: boolean;
readonly isIpad: boolean;
readonly isMobile: boolean;
readonly isTablet: boolean;
readonly isDesktop: boolean;
readonly isChrome: boolean;
readonly isFirefox: boolean;
readonly isSafari: boolean;
readonly isIE: boolean;
readonly isEdge: boolean;
readonly isOpera: boolean;
readonly isMac: boolean;
readonly isChromeOS: boolean;
readonly isWindows: boolean;
readonly isIos: boolean;
readonly isAndroid: boolean;
}UserAgent-based mobile detection isn’t always accurate. Instead, use the following client-side function:
function isMobile() {
const match = window.matchMedia('(pointer:coarse)')
return match && match.matches
}Please see the Changelog for more information on what has changed recently.
astro-useragent is a port from next-useragent to Astro. so big thanks to Tsuyoshi Tokuda and the contributors behind next-useragent package.