inkreachhub/inkreach-official-website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(deploy): production deployment setup and fixes

Browse Source 
- Debian-based api image (bookworm-slim), docker/debian mirrors, prisma
  binaryTargets for openssl 3.0
- nginx: admin SPA under /admin, TLS via acme.sh (ZeroSSL) + auto-renewal
  cron, http->https redirect
- prisma: add origin_goods.delisted migration, sync missing schema
  (good_image/tag_font_color/good_tags), fix users.createdAt Timestamptz
- api: CORS wildcard reflection, helmet CORP cross-origin, price
  backfill in persistProductDetail, categoryIcon ancestor fallback,
  mediaByColor per-color gallery in public goods detail
- admin: /admin base path (vite + router)
- import-data.mjs: udt_name casting, serial sequence advance fix
This commit is contained in:
yeuimu
2026-08-26 14:23:09 +08:00
parent be0b90e68f
commit 6c61a4e871
982 changed files with 74156 additions and 179393 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/vue-debug-guides/reference/ssr-platform-specific-apis.md
-256
View File
@@ -1,256 +0,0 @@
---
title: Guard Platform-Specific APIs in Universal SSR Code
impact: HIGH
impactDescription: Accessing browser-only APIs on server causes crashes; Node.js APIs fail in browser
type: gotcha
tags: [vue3, ssr, browser-api, nodejs, universal, isomorphic, server-side-rendering]
---
# Guard Platform-Specific APIs in Universal SSR Code
**Impact: HIGH** - SSR applications run the same code on both server (Node.js) and client (browser). Browser APIs like `window`, `document`, and `localStorage` don't exist in Node.js and will throw `ReferenceError`. Similarly, Node.js APIs like `fs` and `process` aren't available in browsers.
Universal/isomorphic code must guard platform-specific API access or use libraries that work on both platforms.
## Task Checklist
- [ ] Never access `window`, `document`, `navigator` in `setup()` or `created()`
- [ ] Move browser API access to `onMounted()` lifecycle hook
- [ ] Use `typeof window !== 'undefined'` guard when needed outside lifecycle
- [ ] Use cross-platform libraries for common functionality (fetch, storage)
- [ ] Use Nuxt's `process.client` / `process.server` guards in Nuxt projects
## Common Browser APIs That Break SSR
| API | Node.js Behavior |
|-----|-----------------|
| `window` | `ReferenceError: window is not defined` |
| `document` | `ReferenceError: document is not defined` |
| `localStorage` / `sessionStorage` | `ReferenceError` |
| `navigator` | `ReferenceError` |
| `location` | `ReferenceError` |
| `history` | `ReferenceError` |
| `alert` / `confirm` / `prompt` | `ReferenceError` |
| `requestAnimationFrame` | `ReferenceError` |
| `IntersectionObserver` | `ReferenceError` |
| `ResizeObserver` | `ReferenceError` |
**Incorrect - Crashes on Server:**
```javascript
// WRONG: These run during setup/SSR - crashes in Node.js
const width = ref(window.innerWidth)
const theme = localStorage.getItem('theme')
const userAgent = navigator.userAgent
```
```vue
<script setup>
import { ref } from 'vue'
// WRONG: Runs on server, crashes
const scrollY = ref(window.scrollY)
// WRONG: document doesn't exist on server
document.title = 'My Page'
</script>
```
**Correct - Use onMounted:**
```vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
// Safe defaults that work on server
const width = ref(0)
const theme = ref('light')
const scrollY = ref(0)
onMounted(() => {
// Browser APIs only accessed after mount (client-only)
width.value = window.innerWidth
theme.value = localStorage.getItem('theme') || 'light'
scrollY.value = window.scrollY
// Event listeners safe in mounted
window.addEventListener('resize', handleResize)
window.addEventListener('scroll', handleScroll)
})
onUnmounted(() => {
window.removeEventListener('resize', handleResize)
window.removeEventListener('scroll', handleScroll)
})
function handleResize() {
width.value = window.innerWidth
}
function handleScroll() {
scrollY.value = window.scrollY
}
</script>
```
**Correct - Guard with typeof:**
```javascript
// When you need to check outside lifecycle hooks
function getStoredValue(key, defaultValue) {
if (typeof window !== 'undefined' && window.localStorage) {
return localStorage.getItem(key) ?? defaultValue
}
return defaultValue
}
// Composable with SSR awareness
export function useMediaQuery(query) {
const matches = ref(false)
// Only run on client
if (typeof window !== 'undefined') {
const mediaQuery = window.matchMedia(query)
matches.value = mediaQuery.matches
// Setup listener in lifecycle
onMounted(() => {
const handler = (e) => { matches.value = e.matches }
mediaQuery.addEventListener('change', handler)
onUnmounted(() => mediaQuery.removeEventListener('change', handler))
})
}
return matches
}
```
## Nuxt.js Guards
```vue
<script setup>
// Nuxt provides process.client and process.server
if (process.client) {
// Only runs in browser
window.analytics.track('page_view')
}
if (process.server) {
// Only runs on server
console.log('Rendering on server')
}
</script>
```
```vue
<template>
<!-- ClientOnly component for client-only rendering -->
<ClientOnly>
<BrowserOnlyChart :data="chartData" />
<template #fallback>
<ChartSkeleton />
</template>
</ClientOnly>
</template>
```
## Cross-Platform Libraries
Use libraries that abstract platform differences:
```javascript
// Fetch - works in both Node.js 18+ and browsers
const response = await fetch('/api/data')
// For older Node.js, use node-fetch or axios
import axios from 'axios'
const { data } = await axios.get('/api/data')
```
```javascript
// Universal cookie handling
import Cookies from 'js-cookie' // Client only
import { parse } from 'cookie' // Works both
// In Nuxt, use useCookie()
const token = useCookie('auth-token')
```
## Common Node.js APIs That Break in Browser
| API | Browser Behavior |
|-----|-----------------|
| `fs` | Module not found |
| `path` | Module not found |
| `process` (full) | Undefined or limited |
| `Buffer` | Undefined (unless polyfilled) |
| `__dirname` / `__filename` | Undefined |
| `require()` | Undefined in ES modules |
**Incorrect:**
```javascript
// WRONG: Node.js APIs in universal code
import fs from 'fs'
const config = JSON.parse(fs.readFileSync('./config.json'))
```
**Correct - Separate Server Code:**
```javascript
// server/utils.js - Server-only file
import fs from 'fs'
export function loadConfig() {
return JSON.parse(fs.readFileSync('./config.json'))
}
// app.js - Universal code uses API instead
const config = await fetch('/api/config').then(r => r.json())
```
## Environment Detection Utility
```javascript
// utils/environment.js
export const isClient = typeof window !== 'undefined'
export const isServer = !isClient
export const isBrowser = isClient && typeof document !== 'undefined'
export const isNode = typeof process !== 'undefined' &&
process.versions?.node != null
// Usage
import { isClient, isServer } from '@/utils/environment'
if (isClient) {
// Browser-specific code
}
```
## Third-Party Library Issues
Some libraries auto-access browser APIs on import:
```javascript
// WRONG: Library accesses window on import
import SomeChartLibrary from 'some-chart-library'
// ^ Crashes on server if library does: const x = window.something
```
**Correct - Dynamic Import:**
```vue
<script setup>
import { defineAsyncComponent } from 'vue'
// Dynamic import only loads on client
const Chart = defineAsyncComponent(() =>
import('some-chart-library').then(m => m.ChartComponent)
)
</script>
<template>
<ClientOnly>
<Chart :data="data" />
</ClientOnly>
</template>
```
## Reference
- [Vue.js SSR - Platform-Specific APIs](https://vuejs.org/guide/scaling-up/ssr.html#access-to-platform-specific-apis)
- [Nuxt ClientOnly Component](https://nuxt.com/docs/api/components/client-only)
- [MDN: Web APIs](https://developer.mozilla.org/en-US/docs/Web/API)