chore: move __NO_SIDE_EFFECTS__ into JSDocs

vueuse · antfu · Jul 28, 2025 · Jul 22, 2025 · Jul 22, 2025 · Jul 23, 2025
commit 90135ee204b6809d04116f6f11d92def159cf3a7
diff --git a/packages/core/useActiveElement/index.ts b/packages/core/useActiveElement/index.ts
@@ -24,8 +24,9 @@ export interface UseActiveElementOptions extends ConfigurableWindow, Configurabl
  *
  * @see https://vueuse.org/useActiveElement
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useActiveElement<T extends HTMLElement>(
   options: UseActiveElementOptions = {},
 ) {

diff --git a/packages/core/useBattery/index.ts b/packages/core/useBattery/index.ts
@@ -21,8 +21,9 @@ type NavigatorWithBattery = Navigator & {
  * Reactive Battery Status API.
  *
  * @see https://vueuse.org/useBattery
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useBattery(options: ConfigurableNavigator = {}) {
   const { navigator = defaultNavigator } = options
   const events = ['chargingchange', 'chargingtimechange', 'dischargingtimechange', 'levelchange']

diff --git a/packages/core/useBluetooth/index.ts b/packages/core/useBluetooth/index.ts
@@ -43,7 +43,7 @@ export interface UseBluetoothOptions extends UseBluetoothRequestDeviceOptions, C
   acceptAllDevices?: boolean
 }
 
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function useBluetooth(options?: UseBluetoothOptions): UseBluetoothReturn {
   let {
     acceptAllDevices = false,

diff --git a/packages/core/useBrowserLocation/index.ts b/packages/core/useBrowserLocation/index.ts
@@ -37,8 +37,9 @@ export interface BrowserLocationState {
  * Reactive browser location.
  *
  * @see https://vueuse.org/useBrowserLocation
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useBrowserLocation(options: ConfigurableWindow = {}) {
   const { window = defaultWindow } = options
   const refs = Object.fromEntries(

diff --git a/packages/core/useDeviceOrientation/index.ts b/packages/core/useDeviceOrientation/index.ts
@@ -12,8 +12,9 @@ import { useSupported } from '../useSupported'
  *
  * @see https://vueuse.org/useDeviceOrientation
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useDeviceOrientation(options: ConfigurableWindow = {}) {
   const { window = defaultWindow } = options
   const isSupported = useSupported(() => window && 'DeviceOrientationEvent' in window)

diff --git a/packages/core/useDevicePixelRatio/index.ts b/packages/core/useDevicePixelRatio/index.ts
@@ -8,8 +8,9 @@ import { useMediaQuery } from '../useMediaQuery'
  * Reactively track `window.devicePixelRatio`.
  *
  * @see https://vueuse.org/useDevicePixelRatio
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useDevicePixelRatio(options: ConfigurableWindow = {}) {
   const {
     window = defaultWindow,

diff --git a/packages/core/useDocumentVisibility/index.ts b/packages/core/useDocumentVisibility/index.ts
@@ -8,8 +8,9 @@ import { useEventListener } from '../useEventListener'
  * Reactively track `document.visibilityState`.
  *
  * @see https://vueuse.org/useDocumentVisibility
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useDocumentVisibility(options: ConfigurableDocument = {}): ShallowRef<DocumentVisibilityState> {
   const { document = defaultDocument } = options
   if (!document)

diff --git a/packages/core/useEyeDropper/index.ts b/packages/core/useEyeDropper/index.ts
@@ -28,8 +28,9 @@ export interface UseEyeDropperOptions {
  * Reactive [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API)
  *
  * @see https://vueuse.org/useEyeDropper
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useEyeDropper(options: UseEyeDropperOptions = {}) {
   const { initialValue = '' } = options
   const isSupported = useSupported(() => typeof window !== 'undefined' && 'EyeDropper' in window)

diff --git a/packages/core/useFps/index.ts b/packages/core/useFps/index.ts
@@ -10,7 +10,7 @@ export interface UseFpsOptions {
   every?: number
 }
 
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function useFps(options?: UseFpsOptions): ShallowRef<number> {
   const fps = shallowRef(0)
   if (typeof performance === 'undefined')

diff --git a/packages/core/useGamepad/index.ts b/packages/core/useGamepad/index.ts
@@ -59,7 +59,7 @@ export function mapGamepadToXbox360Controller(gamepad: Ref<Gamepad | undefined>)
   })
 }
 
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function useGamepad(options: UseGamepadOptions = {}) {
   const {
     navigator = defaultNavigator,

diff --git a/packages/core/useKeyModifier/index.ts b/packages/core/useKeyModifier/index.ts
@@ -27,7 +27,7 @@ export interface UseModifierOptions<Initial> extends ConfigurableDocument {
 
 export type UseKeyModifierReturn<Initial> = ShallowRef<Initial extends boolean ? boolean : boolean | null>
 
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function useKeyModifier<Initial extends boolean | null>(modifier: KeyModifier, options: UseModifierOptions<Initial> = {}): UseKeyModifierReturn<Initial> {
   const {
     events = defaultEvents,

diff --git a/packages/core/useMemory/index.ts b/packages/core/useMemory/index.ts
@@ -38,8 +38,9 @@ type PerformanceMemory = Performance & {
  *
  * @see https://vueuse.org/useMemory
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useMemory(options: UseMemoryOptions = {}) {
   const memory = deepRef<MemoryInfo>()
   const isSupported = useSupported(() => typeof performance !== 'undefined' && 'memory' in performance)

diff --git a/packages/core/useNavigatorLanguage/index.ts b/packages/core/useNavigatorLanguage/index.ts
@@ -35,8 +35,8 @@ export interface NavigatorLanguageState {
  * Detects the currently selected user language and returns a reactive language
  * @see https://vueuse.org/useNavigatorLanguage
  *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useNavigatorLanguage(options: ConfigurableWindow = {}): Readonly<NavigatorLanguageState> {
   const { window = defaultWindow } = options
 

diff --git a/packages/core/useNetwork/index.ts b/packages/core/useNetwork/index.ts
@@ -56,8 +56,9 @@ export interface NetworkState {
  *
  * @see https://vueuse.org/useNetwork
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useNetwork(options: ConfigurableWindow = {}): Readonly<NetworkState> {
   const { window = defaultWindow } = options
   const navigator = window?.navigator

diff --git a/packages/core/useOnline/index.ts b/packages/core/useOnline/index.ts
@@ -6,8 +6,9 @@ import { useNetwork } from '../useNetwork'
  *
  * @see https://vueuse.org/useOnline
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useOnline(options: ConfigurableWindow = {}) {
   const { isOnline } = useNetwork(options)
   return isOnline

diff --git a/packages/core/usePageLeave/index.ts b/packages/core/usePageLeave/index.ts
@@ -8,8 +8,9 @@ import { useEventListener } from '../useEventListener'
  *
  * @see https://vueuse.org/usePageLeave
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePageLeave(options: ConfigurableWindow = {}) {
   const { window = defaultWindow } = options
   const isLeft = shallowRef(false)

diff --git a/packages/core/usePermission/index.ts b/packages/core/usePermission/index.ts
@@ -48,6 +48,8 @@ export interface UsePermissionReturnWithControls {
  * Reactive Permissions API.
  *
  * @see https://vueuse.org/usePermission
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export function usePermission(
   permissionDesc: GeneralPermissionDescriptor | GeneralPermissionDescriptor['name'],
@@ -57,7 +59,7 @@ export function usePermission(
   permissionDesc: GeneralPermissionDescriptor | GeneralPermissionDescriptor['name'],
   options: UsePermissionOptions<true>,
 ): UsePermissionReturnWithControls
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function usePermission(
   permissionDesc: GeneralPermissionDescriptor | GeneralPermissionDescriptor['name'],
   options: UsePermissionOptions<boolean> = {},

diff --git a/packages/core/usePreferredColorScheme/index.ts b/packages/core/usePreferredColorScheme/index.ts
@@ -9,8 +9,9 @@ export type ColorSchemeType = 'dark' | 'light' | 'no-preference'
  *
  * @see https://vueuse.org/usePreferredColorScheme
  * @param [options]
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredColorScheme(options?: ConfigurableWindow) {
   const isLight = useMediaQuery('(prefers-color-scheme: light)', options)
   const isDark = useMediaQuery('(prefers-color-scheme: dark)', options)

diff --git a/packages/core/usePreferredContrast/index.ts b/packages/core/usePreferredContrast/index.ts
@@ -9,8 +9,9 @@ export type ContrastType = 'more' | 'less' | 'custom' | 'no-preference'
  *
  * @see https://vueuse.org/usePreferredContrast
  * @param [options]
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredContrast(options?: ConfigurableWindow) {
   const isMore = useMediaQuery('(prefers-contrast: more)', options)
   const isLess = useMediaQuery('(prefers-contrast: less)', options)

diff --git a/packages/core/usePreferredDark/index.ts b/packages/core/usePreferredDark/index.ts
@@ -6,8 +6,9 @@ import { useMediaQuery } from '../useMediaQuery'
  *
  * @see https://vueuse.org/usePreferredDark
  * @param [options]
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredDark(options?: ConfigurableWindow) {
   return useMediaQuery('(prefers-color-scheme: dark)', options)
 }
diff --git a/packages/core/usePreferredLanguages/index.ts b/packages/core/usePreferredLanguages/index.ts
@@ -9,8 +9,9 @@ import { useEventListener } from '../useEventListener'
  *
  * @see https://vueuse.org/usePreferredLanguages
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredLanguages(options: ConfigurableWindow = {}): Ref<readonly string[]> {
   const { window = defaultWindow } = options
   if (!window)

diff --git a/packages/core/usePreferredReducedMotion/index.ts b/packages/core/usePreferredReducedMotion/index.ts
@@ -9,8 +9,9 @@ export type ReducedMotionType = 'reduce' | 'no-preference'
  *
  * @see https://vueuse.org/usePreferredReducedMotion
  * @param [options]
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredReducedMotion(options?: ConfigurableWindow) {
   const isReduced = useMediaQuery('(prefers-reduced-motion: reduce)', options)
 

diff --git a/packages/core/usePreferredReducedTransparency/index.ts b/packages/core/usePreferredReducedTransparency/index.ts
@@ -9,8 +9,9 @@ export type ReducedTransparencyType = 'reduce' | 'no-preference'
  *
  * @see https://vueuse.org/usePreferredReducedTransparency
  * @param [options]
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function usePreferredReducedTransparency(options?: ConfigurableWindow) {
   const isReduced = useMediaQuery('(prefers-reduced-transparency: reduce)', options)
 

diff --git a/packages/core/useSSRWidth/index.ts b/packages/core/useSSRWidth/index.ts
@@ -4,7 +4,7 @@ import { hasInjectionContext } from 'vue'
 
 const ssrWidthSymbol = Symbol('vueuse-ssr-width') as InjectionKey<number | null>
 
-/* #__NO_SIDE_EFFECTS__ */
+/* @__NO_SIDE_EFFECTS__ */
 export function useSSRWidth() {
   // Avoid injection warning outside of components
   const ssrWidth = hasInjectionContext() ? injectLocal(ssrWidthSymbol, null) : null

diff --git a/packages/core/useScreenOrientation/index.ts b/packages/core/useScreenOrientation/index.ts
@@ -22,8 +22,9 @@ export interface ScreenOrientation extends EventTarget {
  * Reactive screen orientation
  *
  * @see https://vueuse.org/useScreenOrientation
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useScreenOrientation(options: ConfigurableWindow = {}) {
   const {
     window = defaultWindow,

diff --git a/packages/core/useTextDirection/index.ts b/packages/core/useTextDirection/index.ts
@@ -33,8 +33,9 @@ export interface UseTextDirectionOptions extends ConfigurableDocument {
  * Reactive dir of the element's text.
  *
  * @see https://vueuse.org/useTextDirection
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useTextDirection(options: UseTextDirectionOptions = {}) {
   const {
     document = defaultDocument,

diff --git a/packages/core/useTextSelection/index.ts b/packages/core/useTextSelection/index.ts
@@ -12,8 +12,9 @@ function getRangesFromSelection(selection: Selection) {
  * Reactively track user text selection based on [`Window.getSelection`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getSelection).
  *
  * @see https://vueuse.org/useTextSelection
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useTextSelection(options: ConfigurableWindow = {}) {
   const {
     window = defaultWindow,

diff --git a/packages/core/useWakeLock/index.ts b/packages/core/useWakeLock/index.ts
@@ -25,8 +25,9 @@ export type UseWakeLockOptions = ConfigurableNavigator & ConfigurableDocument
  *
  * @see https://vueuse.org/useWakeLock
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useWakeLock(options: UseWakeLockOptions = {}) {
   const {
     navigator = defaultNavigator,

diff --git a/packages/core/useWindowFocus/index.ts b/packages/core/useWindowFocus/index.ts
@@ -8,8 +8,9 @@ import { useEventListener } from '../useEventListener'
  * Reactively track window focus with `window.onfocus` and `window.onblur`.
  *
  * @see https://vueuse.org/useWindowFocus
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useWindowFocus(options: ConfigurableWindow = {}): ShallowRef<boolean> {
   const { window = defaultWindow } = options
   if (!window)

diff --git a/packages/core/useWindowSize/index.ts b/packages/core/useWindowSize/index.ts
@@ -36,8 +36,9 @@ export interface UseWindowSizeOptions extends ConfigurableWindow {
  *
  * @see https://vueuse.org/useWindowSize
  * @param options
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function useWindowSize(options: UseWindowSizeOptions = {}) {
   const {
     window = defaultWindow,

diff --git a/packages/shared/createGlobalState/index.ts b/packages/shared/createGlobalState/index.ts
@@ -8,8 +8,9 @@ export type CreateGlobalStateReturn<Fn extends AnyFn = AnyFn> = Fn
  *
  * @see https://vueuse.org/createGlobalState
  * @param stateFactory A factory function to create the state
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function createGlobalState<Fn extends AnyFn>(
   stateFactory: Fn,
 ): CreateGlobalStateReturn<Fn> {

diff --git a/packages/shared/createInjectionState/index.ts b/packages/shared/createInjectionState/index.ts
@@ -18,8 +18,8 @@ export interface CreateInjectionStateOptions<Return> {
  *
  * @see https://vueuse.org/createInjectionState
  *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function createInjectionState<Arguments extends Array<any>, Return>(
   composable: (...args: Arguments) => Return,
   options?: CreateInjectionStateOptions<Return>,

diff --git a/packages/shared/createSharedComposable/index.ts b/packages/shared/createSharedComposable/index.ts
@@ -9,8 +9,9 @@ export type SharedComposableReturn<T extends AnyFn = AnyFn> = T
  * Make a composable function usable with multiple Vue instances.
  *
  * @see https://vueuse.org/createSharedComposable
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 export function createSharedComposable<Fn extends AnyFn>(composable: Fn): SharedComposableReturn<Fn> {
   let subscribers = 0
   let state: ReturnType<Fn> | undefined

diff --git a/packages/shared/injectLocal/index.ts b/packages/shared/injectLocal/index.ts
@@ -9,8 +9,9 @@ import { localProvidedStateMap } from '../provideLocal/map'
  * injectLocal('MyInjectionKey', 1)
  * const injectedValue = injectLocal('MyInjectionKey') // injectedValue === 1
  * ```
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-/* #__NO_SIDE_EFFECTS__ */
 // @ts-expect-error overloads are not compatible
 export const injectLocal: typeof inject = (...args) => {
   const key = args[0] as string | symbol