Index of every page on this site: llms.txt
All skills
robotostudio avatar

/next-best-practices

@c0b29e4
Run it yourself

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

  • 20 files
  • 78.7 KB
  • Updated 5 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/robotostudio/turbo-start-sanity/next-best-practices

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

bundling.md

≈1.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Bundling

Fix common bundling issues with third-party packages.

Server-Incompatible Packages

Some packages use browser APIs (window, document, localStorage) and fail in Server Components.

Error Signs

ReferenceError: window is not defined
ReferenceError: document is not defined
ReferenceError: localStorage is not defined
Module not found: Can't resolve 'fs'

Solution 1: Mark as Client-Only

If the package is only needed on client:

// Bad: Fails - package uses window
import SomeChart from 'some-chart-library'

export default function Page() {
  return <SomeChart />
}

// Good: Use dynamic import with ssr: false
import dynamic from 'next/dynamic'

const SomeChart = dynamic(() => import('some-chart-library'), {
  ssr: false,
})

export default function Page() {
  return <SomeChart />
}

Solution 2: Externalize from Server Bundle

For packages that should run on server but have bundling issues:

// next.config.js
module.exports = {
  serverExternalPackages: ['problematic-package'],
}

Use this for:

  • Packages with native bindings (sharp, bcrypt)
  • Packages that don't bundle well (some ORMs)
  • Packages with circular dependencies

Solution 3: Client Component Wrapper

Wrap the entire usage in a client component:

// components/ChartWrapper.tsx
'use client'

import { Chart } from 'chart-library'

export function ChartWrapper(props) {
  return <Chart {...props} />
}

// app/page.tsx (server component)
import { ChartWrapper } from '@/components/ChartWrapper'

export default function Page() {
  return <ChartWrapper data={data} />
}

CSS Imports

Import CSS files instead of using <link> tags. Next.js handles bundling and optimization.

// Bad: Manual link tag
<link rel="stylesheet" href="/styles.css" />

// Good: Import CSS
import './styles.css'

// Good: CSS Modules
import styles from './Button.module.css'

Polyfills

Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.

Already included: Array.from, Object.assign, Promise, fetch, Map, Set, Symbol, URLSearchParams, and 50+ others.

// Bad: Redundant polyfills
<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />

// Good: Next.js includes these automatically

ESM/CommonJS Issues

Error Signs

SyntaxError: Cannot use import statement outside a module
Error: require() of ES Module
Module not found: ESM packages need to be imported

Solution: Transpile Package

// next.config.js
module.exports = {
  transpilePackages: ['some-esm-package', 'another-package'],
}

Common Problematic Packages

Package Issue Solution
sharp Native bindings serverExternalPackages: ['sharp']
bcrypt Native bindings serverExternalPackages: ['bcrypt'] or use bcryptjs
canvas Native bindings serverExternalPackages: ['canvas']
recharts Uses window dynamic(() => import('recharts'), { ssr: false })
react-quill Uses document dynamic(() => import('react-quill'), { ssr: false })
mapbox-gl Uses window dynamic(() => import('mapbox-gl'), { ssr: false })
monaco-editor Uses window dynamic(() => import('@monaco-editor/react'), { ssr: false })
lottie-web Uses document dynamic(() => import('lottie-react'), { ssr: false })

Bundle Analysis

Analyze bundle size with the built-in analyzer (Next.js 16.1+):

next experimental-analyze

This opens an interactive UI to:

  • Filter by route, environment (client/server), and type
  • Inspect module sizes and import chains
  • View treemap visualization

Save output for comparison:

next experimental-analyze --output
# Output saved to .next/diagnostics/analyze

Reference: https://nextjs.org/docs/app/guides/package-bundling

Migrating from Webpack to Turbopack

Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:

// next.config.js
module.exports = {
  // Good: Works with Turbopack
  serverExternalPackages: ['package'],
  transpilePackages: ['package'],

  // Bad: Webpack-only - migrate away from this
  webpack: (config) => {
    // custom webpack config
  },
}

Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c0b29e4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago
user-invocable
false

README badge

README badge for robotostudio/turbo-start-sanity/next-best-practices