🚀 Framework-agnostic device detection for Node.js with Material UI breakpoint mapping for SSR and client-side usage.
- 📱 Device Detection: Detects mobile, tablet, and desktop devices from the user-agent string.
- 🎯 Material UI Breakpoints: Maps devices to Material UI (MUI) breakpoints (
xs
,sm
,md
, etc.) for responsive design. - ⚡ Universal Usage: Works seamlessly in server-side (SSR) and client-side environments.
- 🧩 Framework-Agnostic: Easily integrates with Node.js, Next.js, Express, Fastify, and more.
- 🏗 Lightweight & Fast: Built on
ua-parser-js
for minimal overhead and high performance.
Install the package using your preferred package manager:
# Using pnpm
pnpm add @livepixie-open/device-detector
# Using npm
npm install @livepixie-open/device-detector
# Using yarn
yarn add @livepixie-open/device-detector
import { detectDevice } from "@livepixie-open/device-detector";
const userAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)";
const device = detectDevice(userAgent);
console.log(device);
// Output:
// {
// type: "mobile",
// breakpoint: "xs",
// userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)",
// model: "iPhone"
// }
The library supports detection for a wide range of devices. Here are some examples:
// Desktop
console.log(detectDevice("Mozilla/5.0 (Windows NT 10.0; Win64; x64)"));
// Output: { type: "desktop", breakpoint: "md", userAgent: "...", model: undefined }
// Tablet
console.log(detectDevice("Mozilla/5.0 (iPad; CPU OS 15_0 like Mac OS X)"));
// Output: { type: "tablet", breakpoint: "sm", userAgent: "...", model: "iPad" }
// Mobile
console.log(detectDevice("Mozilla/5.0 (Linux; Android 12; Samsung Galaxy Z Fold3)"));
// Output: { type: "mobile", breakpoint: "sm", userAgent: "...", model: "Samsung Galaxy Z Fold3" }
import { detectDevice } from "@livepixie-open/device-detector";
export const getServerSideProps = (context) => {
const userAgent = context.req.headers["user-agent"] || "";
const device = detectDevice(userAgent);
return {
props: {
device,
},
};
};
export default function Home({ device }) {
return (
<div>
<h1>Your device: {device.type}</h1>
<p>Breakpoint: {device.breakpoint}</p>
</div>
);
}
import express from "express";
import { detectDevice } from "@livepixie-open/device-detector";
const app = express();
app.use((req, res, next) => {
const userAgent = req.headers["user-agent"] || "";
req.device = detectDevice(userAgent);
next();
});
app.get("/", (req, res) => {
res.send(`Your device: ${req.device.type}, Breakpoint: ${req.device.breakpoint}`);
});
app.listen(3000, () => console.log("Server running on http://localhost:3000"));
pnpm install
pnpm lint
pnpm test
pnpm build
pnpm publish --access public
Detects the device type and maps it to a Material UI breakpoint.
-
userAgent
: The user-agent string to analyze.
An object with the following properties:
-
type
: The device type ("mobile"
,"tablet"
, or"desktop"
). -
breakpoint
: The corresponding Material UI breakpoint ("xs"
,"sm"
,"md"
, etc.). -
userAgent
: The original user-agent string. -
model
: The device model (if available).
If the library encounters an unknown or unsupported user-agent string, it will default to:
{ "type": "desktop", "breakpoint": "md", "userAgent": "..." }
You can extend the library to support custom breakpoint mappings by modifying the source code or opening a feature request.
MIT License © 2025 Live Pixie Open Source
We welcome contributions! Here’s how you can help:
- Report Issues: Found a bug? Open an issue on GitHub.
- Submit Pull Requests: Have a fix or feature? Submit a PR!
- Star the Repo: If you find this project useful, give it a ⭐ on GitHub.
We’d love to hear your feedback! Reach out to us via:
- GitHub Issues: https://github.com/livepixie-open/device-detector/issues
- Email: opensource@livepixie.com
🔥 Happy Coding! 🚀
- Added Framework Integration Examples: Included detailed examples for Next.js and Express.js.
-
API Reference: Added a clear API reference for the
detectDevice
function. - Troubleshooting Section: Added a section to address common issues like unknown user-agent strings.
- Feedback Section: Encouraged users to provide feedback and report issues.
- Better Organization: Improved the flow and readability of the document.