Skip to content

Commit 5483663

Browse files
DamianGlowalaDamianGlowala
committed
chore: update README and module options JSDoc
1 parent 0aac64a commit 5483663

2 files changed

Lines changed: 80 additions & 90 deletions

File tree

‎README.md‎

Lines changed: 77 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -22,71 +22,68 @@ npx nuxi@latest module add device
2222
2323
## Flags
2424

25-
You can use these flags to detect the device type.
25+
You can use the following flags to detect the device type:
26+
27+
- `$device.isDesktop`
28+
- `$device.isMobile`
29+
- `$device.isTablet`
30+
- `$device.isMobileOrTablet`
31+
- `$device.isDesktopOrTablet`
32+
- `$device.isIos`
33+
- `$device.isWindows`
34+
- `$device.isMacOS`
35+
- `$device.isApple`
36+
- `$device.isAndroid`
37+
- `$device.isFirefox`
38+
- `$device.isEdge`
39+
- `$device.isChrome`
40+
- `$device.isSafari`
41+
- `$device.isSamsung`
42+
- `$device.isCrawler`
43+
44+
The user agent is also injected and accessible with `$device.userAgent`.
45+
46+
The crawler detection is powered by the [crawler-user-agents](https://github.com/monperrus/crawler-user-agents) package.
2647

27-
```js
28-
$device.isDesktop
29-
$device.isMobile
30-
$device.isTablet
31-
$device.isMobileOrTablet
32-
$device.isDesktopOrTablet
33-
$device.isIos
34-
$device.isWindows
35-
$device.isMacOS
36-
$device.isApple
37-
$device.isAndroid
38-
$device.isFirefox
39-
$device.isEdge
40-
$device.isChrome
41-
$device.isSafari
42-
$device.isSamsung
43-
$device.isCrawler
44-
```
48+
## Usage
4549

46-
The user agent is also injected an accessible with `$device.userAgent`.
50+
You can either use the `useDevice()` composable inside a `script setup`, or the `$device` helper directly in the template:
4751

48-
## Usage
52+
```vue
53+
<template>
54+
<div>
55+
<div v-if="$device.isDesktop">Desktop</div>
4956
50-
### Composable
57+
<div v-else-if="$device.isTablet">Tablet</div>
5158
52-
You can use the `useDevice()` composable inside a `script setup` to access the flags.
59+
<div v-else>Mobile</div>
60+
</div>
61+
</template>
5362
54-
```js
5563
<script setup>
56-
const { isMobile } = useDevice();
64+
const { isMobile } = useDevice()
5765
</script>
5866
```
5967

68+
### Changing Layout Dynamically
6069

61-
### Switch a view
62-
63-
```html
70+
```vue
6471
<template>
65-
<section>
66-
<div v-if="$device.isDesktop">
67-
Desktop
68-
</div>
69-
<div v-else-if="$device.isTablet">
70-
Tablet
71-
</div>
72-
<div v-else>
73-
Mobile
74-
</div>
75-
</section>
72+
<div>
73+
<NuxtLayout :name="$device.isMobile ? 'mobile' : 'default'">
74+
<!-- page content -->
75+
</NuxtLayout>
76+
</div>
7677
</template>
77-
```
7878
79-
Of course, you can use `$device` via `this` in a script.
80-
81-
### Change a layout dynamically
82-
83-
```js
84-
export default {
85-
layout: (ctx) => ctx.$device.isMobile ? 'mobile' : 'default'
86-
}
79+
<script setup>
80+
definePageMeta({
81+
layout: false
82+
})
83+
</script>
8784
```
8885

89-
### Add a custom flag
86+
<!-- ### Adding a Custom Flag
9087
9188
You can add other flags to `$device` by adding a [Nuxt plugin](https://nuxtjs.org/docs/2.x/directory-structure/plugins):
9289
@@ -95,66 +92,59 @@ You can add other flags to `$device` by adding a [Nuxt plugin](https://nuxtjs.or
9592
export default function ({ $device }) {
9693
$device.isCustom = $device.userAgent.includes('Custom-Agent') ? true : false
9794
}
98-
```
95+
``` -->
9996

10097
### Options
10198

102-
`defaultUserAgent` option can be used when running `npm run generate`.
99+
#### `defaultUserAgent`
103100

104-
```js
105-
{
106-
modules: ['@nuxtjs/device'],
107-
device: {
108-
defaultUserAgent: 'Mozilla/5.0 (Linux; Android 5.1.1; Nexus 6 Build/LYZ28E) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Mobile Safari/537.36'
109-
}
110-
}
111-
```
101+
Sets the default value for the `user-agent` header (useful when running `npm run generate`).
112102

113-
`refreshOnResize` refresh flags when the window resized.(default: false)
103+
Default: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Safari/537.36`
114104

115-
```js
116-
{
117-
modules: ['@nuxtjs/device'],
118-
device: {
119-
refreshOnResize: true
120-
}
121-
}
122-
```
105+
#### `enabled`
106+
107+
Enables the module conditionally.
108+
109+
Default: `true`
110+
111+
> [!WARNING]
112+
> This option is deprecated. It will be removed in the next major release.
113+
114+
#### `refreshOnResize`
115+
116+
Refreshes flags on window resize.
123117

124-
Note that the default user agent value is set to `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Safari/537.36`.
125-
## CloudFront Support
118+
Default: `false`
126119

127-
If the `user-agent` is `Amazon CloudFront`, this module checks the following headers :
120+
> [!WARNING]
121+
> This option is deprecated. It will be removed in the next major release.
128122
123+
## Amazon CloudFront Support
124+
125+
If the user agent is `Amazon CloudFront`, the module checks for the following headers:
126+
127+
- `CloudFront-Is-Android-Viewer`
128+
- `CloudFront-Is-Desktop-Viewer`
129+
- `CloudFront-Is-IOS-Viewer`
129130
- `CloudFront-Is-Mobile-Viewer`
130131
- `CloudFront-Is-Tablet-Viewer`
131-
- `CloudFront-Is-Desktop-Viewer`
132-
- `CloudFront-Is-Ios-Viewer`
133-
- `CloudFront-Is-Android-Viewer`
134-
135-
Here are the details about the headers:
136-
[Amazon CloudFront - Headers for determining the viewer's device type
137-
](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-cloudfront-headers.html#cloudfront-headers-device-type)
138132

139-
### Caution
133+
Read more about determining the viewer's device type in the [Amazon CloudFront docs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-device-type).
140134

141-
`isWindows` and `isMacOS` flags are not available with CloudFront.
135+
> [!CAUTION]
136+
> `isWindows` and `isMacOS` flags are not available in Amazon CloudFront.
142137
143138
## Cloudflare Support
144139

145-
This module checks the header `CF-Device-Type`.
140+
This module checks for the `CF-Device-Type` header.
146141

147-
Here are the details about the header:
148-
https://support.cloudflare.com/hc/en-us/articles/229373388-Cache-Content-by-Device-Type-Mobile-Tablet-Desktop-
142+
Read more about the device type detection in the [Cloudflare docs](https://developers.cloudflare.com/automatic-platform-optimization/reference/cache-device-type).
149143

150144
## License
151145

152146
[MIT License](./LICENSE)
153147

154-
## Data Source
155-
156-
This module uses [crawler-user-agents](https://github.com/monperrus/crawler-user-agents) to generate the regular expression that detect a crawler.
157-
158148
<!-- Badges -->
159149
[npm-version-src]: https://img.shields.io/npm/v/@nuxtjs/device/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
160150
[npm-version-href]: https://npmjs.com/package/@nuxtjs/device

‎src/types.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
export interface ModuleOptions {
22
/**
3-
* Device Module Default User Agent
3+
* Sets the default value for the `user-agent` header (useful when running `npm run generate`).
44
* @default 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.39 Safari/537.36'
55
*/
66
defaultUserAgent?: string
77

88
/**
9-
* Whether to enable the module conditionally.
9+
* Enables the module conditionally.
1010
* @default true
1111
* @deprecated
1212
*/
1313
enabled?: boolean
1414

1515
/**
16-
* Refresh Device Module Values On Window Resize
16+
* Refreshes flags on window resize.
1717
* @default false
1818
* @deprecated
1919
*/

0 commit comments

Comments
 (0)