From c737bc5f4fd4a4a1520c42bf4f06662f8701d324 Mon Sep 17 00:00:00 2001
From: koa-wang <hi_leo@yeah.net>
Date: Sat, 10 Oct 2026 15:28:42 +0800
Subject: [PATCH] feat(inspector): add side effects indicator for packages

Display whether a package has side effects declared in package.json,
helping users debug tree-shaking issues at a glance.

Closes #100
---
 .../components/display/SideEffectsBadge.vue   | 45 +++++++++++++++++++
 .../src/app/components/grid/Item.vue          |  3 ++
 .../components/panel/PackageDetailsInfo.vue   |  2 +
 .../src/app/components/panel/Settings.vue     |  3 ++
 .../src/app/state/settings.ts                 |  1 +
 .../src/shared/types.ts                       |  1 +
 .../node-modules-tools/src/resolve-json.ts    |  4 +-
 packages/node-modules-tools/src/types/node.ts |  8 ++++
 .../src/utils/package-json.ts                 | 17 +++++++
 9 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 packages/node-modules-inspector/src/app/components/display/SideEffectsBadge.vue

diff --git a/packages/node-modules-inspector/src/app/components/display/SideEffectsBadge.vue b/packages/node-modules-inspector/src/app/components/display/SideEffectsBadge.vue
new file mode 100644
index 00000000..453e4f52
--- /dev/null
+++ b/packages/node-modules-inspector/src/app/components/display/SideEffectsBadge.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import type { PackageNode } from 'node-modules-tools'
+import { computed } from 'vue'
+import { settings } from '../../state/settings'
+
+const props = defineProps<{
+  pkg: PackageNode
+  class?: string
+}>()
+
+const sideEffects = computed(() => props.pkg.resolved?.sideEffects)
+
+const isShown = computed(() => {
+  if (!settings.value.showSideEffectsBadge)
+    return false
+  return sideEffects.value !== undefined
+})
+
+const icon = computed(() => {
+  if (sideEffects.value === false)
+    return 'i-ph:tree-structure-duotone text-green-400'
+  if (sideEffects.value === true)
+    return 'i-ph:warning-circle-duotone text-amber-400'
+  // array of file paths
+  return 'i-ph:warning-circle-duotone text-yellow-400'
+})
+
+const description = computed(() => {
+  if (sideEffects.value === false)
+    return 'This package has no side effects (safe to tree-shake)'
+  if (sideEffects.value === true)
+    return 'This package has side effects (may not be fully tree-shakeable)'
+  if (Array.isArray(sideEffects.value))
+    return `This package has side effects in ${sideEffects.value.length} file pattern(s) (partially tree-shakeable)`
+  return undefined
+})
+</script>
+
+<template>
+  <span
+    v-if="isShown" v-tooltip="description"
+    :class="[props.class, icon]"
+    h-1.1em inline-flex align-middle
+  />
+</template>
diff --git a/packages/node-modules-inspector/src/app/components/grid/Item.vue b/packages/node-modules-inspector/src/app/components/grid/Item.vue
index 584bd800..d9fbad84 100644
--- a/packages/node-modules-inspector/src/app/components/grid/Item.vue
+++ b/packages/node-modules-inspector/src/app/components/grid/Item.vue
@@ -8,6 +8,7 @@ import DisplayDateBadge from '../display/DateBadge.vue'
 import DisplayFileSizeBadge from '../display/FileSizeBadge.vue'
 import DisplayModuleType from '../display/ModuleType'
 import DisplayPackageSpec from '../display/PackageSpec.vue'
+import DisplaySideEffectsBadge from '../display/SideEffectsBadge.vue'
 import DisplaySourceTypeBadge from '../display/SourceTypeBadge.vue'
 import UiPackageBorder from '../ui/PackageBorder.vue'
 
@@ -55,6 +56,8 @@ defineProps<{
 
       <DisplaySourceTypeBadge :pkg />
 
+      <DisplaySideEffectsBadge :pkg />
+
       <!--
       <span op-mute>·</span>
       <div op75>
diff --git a/packages/node-modules-inspector/src/app/components/panel/PackageDetailsInfo.vue b/packages/node-modules-inspector/src/app/components/panel/PackageDetailsInfo.vue
index 3c54ef3e..3c8fde3d 100644
--- a/packages/node-modules-inspector/src/app/components/panel/PackageDetailsInfo.vue
+++ b/packages/node-modules-inspector/src/app/components/panel/PackageDetailsInfo.vue
@@ -15,6 +15,7 @@ import DisplayDateBadge from '../display/DateBadge.vue'
 import DisplayModuleType from '../display/ModuleType'
 import DisplayNodeVersionRange from '../display/NodeVersionRange.vue'
 import DisplayPackageName from '../display/PackageName.vue'
+import DisplaySideEffectsBadge from '../display/SideEffectsBadge.vue'
 import DisplaySourceTypeBadge from '../display/SourceTypeBadge.vue'
 import DisplaySupplyChainBadge from '../display/SupplyChainBadge.vue'
 import DisplayVersionWithUpdates from '../display/VersionWithUpdates.vue'
@@ -59,6 +60,7 @@ function showDuplicatedGraph(pkgs: PackageNode[]) {
     >
       <template #after>
         <DisplaySupplyChainBadge :pkg class="ml-1" />
+        <DisplaySideEffectsBadge :pkg class="ml-1" />
       </template>
     </DisplayPackageName>
 
diff --git a/packages/node-modules-inspector/src/app/components/panel/Settings.vue b/packages/node-modules-inspector/src/app/components/panel/Settings.vue
index 5b78099b..abd87f02 100644
--- a/packages/node-modules-inspector/src/app/components/panel/Settings.vue
+++ b/packages/node-modules-inspector/src/app/components/panel/Settings.vue
@@ -43,6 +43,9 @@ const showConfigDialog = ref(false)
           :titles="['Present', 'Absent', 'None']"
         />
       </OptionItem>
+      <OptionItem :div="true" title="Show side effects badge" description="Show whether a package has side effects">
+        <FormCheckbox v-model="settings.showSideEffectsBadge" />
+      </OptionItem>
       <OptionItem :div="true" title="Colorize size badge" description="Colorize package size badge">
         <FormCheckbox v-model="settings.colorizePackageSize" />
       </OptionItem>
diff --git a/packages/node-modules-inspector/src/app/state/settings.ts b/packages/node-modules-inspector/src/app/state/settings.ts
index 0531872e..7bf64592 100644
--- a/packages/node-modules-inspector/src/app/state/settings.ts
+++ b/packages/node-modules-inspector/src/app/state/settings.ts
@@ -12,6 +12,7 @@ export const SETTINGS_DEFAULT: SettingsOptions = {
   showInstallSizeBadge: true,
   showPublishTimeBadge: false,
   showSupplyChainBadge: 'present',
+  showSideEffectsBadge: false,
   showFileComposition: false,
   showDependencySourceBadge: 'dev',
   showPublintMessages: false,
diff --git a/packages/node-modules-inspector/src/shared/types.ts b/packages/node-modules-inspector/src/shared/types.ts
index a6a97000..547db0ec 100644
--- a/packages/node-modules-inspector/src/shared/types.ts
+++ b/packages/node-modules-inspector/src/shared/types.ts
@@ -81,6 +81,7 @@ export interface SettingsOptions {
   showInstallSizeBadge: boolean
   showPublishTimeBadge: boolean
   showSupplyChainBadge: 'present' | 'absent' | 'none'
+  showSideEffectsBadge: boolean
   showFileComposition: boolean
   showDependencySourceBadge: 'none' | 'dev' | 'prod' | 'both'
   treatFauxAsESM: boolean
diff --git a/packages/node-modules-tools/src/resolve-json.ts b/packages/node-modules-tools/src/resolve-json.ts
index d70b860f..407f666c 100644
--- a/packages/node-modules-tools/src/resolve-json.ts
+++ b/packages/node-modules-tools/src/resolve-json.ts
@@ -2,8 +2,7 @@ import type { PackageJson } from 'pkg-types'
 import type { PackageNode } from './types'
 import { objectPick } from '@antfu/utils'
 import { analyzePackageModuleType } from './analyze-esm'
-import { normalizePkgAuthors, normalizePkgFundings, normalizePkgLicense, normalizePkgRepository } from './utils/package-json'
-
+import { normalizePkgAuthors, normalizePkgFundings, normalizePkgLicense, normalizePkgRepository, normalizePkgSideEffects } from './utils/package-json'
 // @keep-unique
 // @keep-sorted
 export const PACKAGE_JSON_KEYS = [
@@ -46,5 +45,6 @@ export function resolvePackageJsonFields(json: PackageJson): Omit<PackageNode['r
     repository: normalizePkgRepository(json),
     license: normalizePkgLicense(json),
     fundings: normalizePkgFundings(json),
+    sideEffects: normalizePkgSideEffects(json),
   }
 }
diff --git a/packages/node-modules-tools/src/types/node.ts b/packages/node-modules-tools/src/types/node.ts
index c9493664..71c58c4e 100644
--- a/packages/node-modules-tools/src/types/node.ts
+++ b/packages/node-modules-tools/src/types/node.ts
@@ -90,6 +90,14 @@ export interface PackageNode extends PackageNodeBase {
     license?: ParsedLicense
     /** Parsed funding entries with avatars when known */
     fundings?: ParsedFunding[]
+    /***
+     * Whether the package has side effects.
+     * - `true` (default): the package has side effects (cannot be tree-shaken)
+     * - `false`: the package has no side effects (safe to tree-shake)
+     * - `string[]`: specific file paths that have side effects
+     * - `undefined`: not declared in package.json
+     */
+    sideEffects?: boolean | string[]
   }
 }
 export type AuditLevelString = 'low' | 'moderate' | 'high' | 'critical'
diff --git a/packages/node-modules-tools/src/utils/package-json.ts b/packages/node-modules-tools/src/utils/package-json.ts
index 6bc45568..ffde821e 100644
--- a/packages/node-modules-tools/src/utils/package-json.ts
+++ b/packages/node-modules-tools/src/utils/package-json.ts
@@ -238,6 +238,23 @@ export interface ParsedRepository {
   org?: string
 }
 
+/**
+ * Normalize the `sideEffects` field from package.json.
+ * Can be a boolean or an array of file paths.
+ * Returns `undefined` if not declared.
+ */
+
+export function normalizePkgSideEffects(json: PackageJson): boolean | string[] | undefined {
+  const raw = (json as Record<string, unknown>).sideEffects
+  if (raw === undefined)
+    return undefined
+  if (typeof raw === 'boolean')
+    return raw
+  if (Array.isArray(raw))
+    return raw.filter((item): item is string => typeof item === 'string')
+  return undefined
+}
+
 export function normalizePkgRepository(json: PackageJson): ParsedRepository | undefined {
   if (!json.repository && !json.bugs)
     return undefined