astro-useragent
v4.1.0
Published
Parses browser user-agent strings for Astro
Downloads
1,025
Readme
🚀 Astro UserAgent
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.
📦 Installation
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-useragent🥑 Usage
Enable SSR mode
To 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.
Usage with Astro pages
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
Usage with Astro API routes
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
Parsed object interface
The parsed UserAgent object will have the following interface:
export interface UserAgent {
readonly source: string | null; // The original user agent string.
readonly browser: string | null;
readonly browserVersion: number;
readonly cpu: string | null;
readonly deviceType: string | null;
readonly deviceVendor: string | null;
readonly engine: string | null;
readonly engineVersion: number | null;
readonly os: string | null;
readonly osVersion: number | null;
readonly isAndroid: boolean;
readonly isChrome: boolean;
readonly isChromeOS: boolean;
readonly isDesktop: boolean;
readonly isEdge: boolean;
readonly isFirefox: boolean;
readonly isIE: boolean;
readonly isIos: boolean;
readonly isIpad: boolean;
readonly isIphone: boolean;
readonly isMac: boolean;
readonly isMobile: boolean;
readonly isOpera: boolean;
readonly isSafari: boolean;
readonly isTablet: boolean;
readonly isWindows: boolean;
readonly isBot: boolean;
readonly isAIBot: boolean;
readonly isChromeFamily: boolean;
readonly isAppleSilicon: boolean;
getUA(): string;
getBrowser(): IBrowser;
getCPU(): ICPU;
getDevice(): IDevice;
getEngine(): IEngine;
getOS(): IOS;
}Caveats
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;
}Changelog
Please see the Changelog for more information on what has changed recently.
Acknowledgements
astro-useragent is a port from next-useragent to Astro. so big thanks to the contributors behind next-useragent package.