Communitygithub.com

Nuvraxis/nuvraxis-plugins

>- Helm chart rules for Nuvraxis Next.js apps — one chart per app in charts/ (named after the app), published to oci://ghcr.io/nuvraxis/charts and synced by Argo CD; Chart.yaml version/appVersion set only by release.yaml; Deployment with startup/liveness/readiness probes on /api/health, non-root read-only security context, emptyDir for .next/cache, ConfigMap + existing Secret via envFrom, Service, Ingress with cert-manager, HPA, PDB, ServiceAccount, topology spread; no Helm hooks; helm lint --strict + kubeconform. Use when the repo has charts/, Chart.yaml, values*.yaml, templates/*.yaml with Helm syntax, or an Argo CD Application, or when asked to deploy, scale, expose or configure the app on Kubernetes.

What is nuvraxis-plugins?

nuvraxis-plugins is a Claude Code agent skill that >- Helm chart rules for Nuvraxis Next.js apps — one chart per app in charts/ (named after the app), published to oci://ghcr.io/nuvraxis/charts and synced by Argo CD; Chart.yaml version/appVersion set only by release.yaml; Deployment with startup/liveness/readiness probes on /api/health, non-root read-only security context, emptyDir for .next/cache, ConfigMap + existing Secret via envFrom, Service, Ingress with cert-manager, HPA, PDB, ServiceAccount, topology spread; no Helm hooks; helm lint --strict + kubeconform. Use when the repo has charts/, Chart.yaml, values*.yaml, templates/*.yaml with Helm syntax, or an Argo CD Application, or when asked to deploy, scale, expose or configure the app on Kubernetes.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/helm-nextjs
View original→Browse all skills

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Helm chart for a Next.js app

Use for charts/<app>/ and how Argo CD consumes it. The image it runs comes from docker-nextjs; the pipeline that publishes both is github-actions.

The template's charts/__APP__/ is the source of truth. All values with comments: references/values.md. Argo CD wiring: references/argocd.md.

Rules

  1. One chart per app, at charts/<app>/ in the app's repo root. Why there: Argo CD can sync it straight from git (path: charts/<app>) for a dev environment and from the OCI registry for production, with the same files; it's outside apps/, so it's neither in the Docker build context nor a pnpm workspace package; and the chart changes in the same PR as the code that needs it. The chart is single-app on purpose: no umbrella, no subcharts. Generic, values-driven templates (like the backend umbrella chart) only where a single app needs the switch: ingress, HPA, PDB, topology spread.

  2. Never hand-edit version or appVersion. Both stay 0.0.0 in git. release.yaml runs helm package --version X.Y.Z --app-version vX.Y.Z from the tag vX.Y.Z, so the published chart and the image tag always match.

  3. image.tag defaults to appVersion; set it only for git-synced environments. From OCI, appVersion is the release tag and the image is ghcr.io/nuvraxis/<app>:vX.Y.Z. Synced from git, appVersion is 0.0.0, so the Argo CD Application sets image.tag: sha-<short-sha> (or main). image.repository is lowercase, always.

  4. Probes: startup, liveness and readiness, all on /api/health. The startup probe (2s × 30) covers boot; liveness and readiness only start after it. The route never touches a dependency, so a database outage doesn't restart pods. Don't point a probe at /: it renders a page.

  5. Security context matches the image: uid/gid 1001, runAsNonRoot, readOnlyRootFilesystem, no privilege escalation, all capabilities dropped, RuntimeDefault seccomp. automountServiceAccountToken: false on both the ServiceAccount and the pod: the app doesn't call the Kubernetes API.

  6. .next/cache is an emptyDir with a sizeLimit. It's the only writable path (/app/apps/<app>/.next/cache). The limit keeps a runaway image cache from filling the node.

  7. Configuration through envFrom: a ConfigMap from values.config, and a Secret that already exists.

    config:
  API_BASE_URL: https://api.nuvraxis.com
existingSecret: portal-secrets

    The chart never templates secret values: no kind: Secret with data from values, no --set secret=…. The Secret is created by External Secrets, Sealed Secrets or an operator, and only its name is in values. A ConfigMap change rolls the pods through the checksum/config annotation.

  8. No NEXT_PUBLIC_* in the chart. They're baked in at image build (see docker-nextjs); setting them at runtime does nothing.

  9. Resources: requests for CPU and memory, a memory limit, no CPU limit. CPU limits throttle a Node server during bursts and inflate tail latency; the memory limit stays because Node's heap grows to what it's given.

  10. High availability by default: 2 replicas, PDB maxUnavailable: 1, rolling update with maxUnavailable: 0, topology spread across zones and nodes (ScheduleAnyway). With autoscaling.enabled the Deployment omits replicas, so Argo CD and the HPA don't fight over it.

  11. Ingress is opt-in, TLS through cert-manager annotations. ingress.enabled, className, hosts, tls with a secretName, and cert-manager.io/cluster-issuer in annotations. For streaming responses on ingress-nginx add nginx.ingress.kubernetes.io/proxy-buffering: "off"; for rate limiting, limit-rps (see nextjs-security).

  12. No Helm hooks, no lookup, no random values. Argo CD renders the chart with helm template and applies the result: hooks become Argo hooks with different semantics, lookup returns nothing, and randAlphaNum changes on every sync and shows the app permanently out of sync. Everything rendered must be a pure function of the values.

  13. Private GHCR packages need pull credentials. GHCR packages are private on first push. For images: a docker-registry Secret with a token that has read:packages, referenced in imagePullSecrets (production values reference ghcr-pull). For the chart in Argo CD: a repository Secret with enableOCI: "true" (see references/argocd.md). Or make the packages public in GitHub if the code is public.

  14. values-production.yaml holds only what differs in production. Layer it: -f values.yaml -f values-production.yaml. Don't copy the defaults into it.

  15. Validate with helm lint --strict and helm template | kubeconform -strict. Why kubeconform over helm-unittest: the bugs a single-app chart actually has are wrong field names, types or API versions in the rendered output, which kubeconform catches against the real Kubernetes schemas with zero test code. helm-unittest asserts template logic, which this chart barely has. Lint and validate both values files, as pr.yaml does.

Adding things

NeedChange
A runtime env varconfig: in values (non-secret) or a key in the existing Secret
A secretadd it to the external Secret; nothing in the chart changes
Another port or sidecarjustify it first; a Next app needs one port
A cron joba separate chart or app, not this Deployment
NetworkPolicyadd templates/networkpolicy.yaml, toggled by networkPolicy.enabled

Verify

helm lint --strict charts/<app>
helm lint --strict charts/<app> -f charts/<app>/values-production.yaml
helm template <app> charts/<app> -f charts/<app>/values-production.yaml \
  | docker run --rm -i ghcr.io/yannh/kubeconform:v0.8.0 -strict -summary -kubernetes-version 1.34.0 -

Sources

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Nuvraxis/nuvraxis-plugins

>- Biome 2.5 setup and rules for Nuvraxis monorepos — root biome.json with pinned $schema, VCS ignore, formatter settings, the recommended preset with a11y and the react/next domains, nursery policy, organize imports, overrides, nested per-package configs ("extends": "//"), biome check --write locally, biome ci in CI, VS Code settings, and migrating from ESLint/Prettier. Use when the repo has biome.json or biome.jsonc, @biomejs/biome in package.json, .eslintrc*/eslint.config.*/.prettierrc* to migrate, or when fixing lint and formatting errors.

Nuvraxis/nuvraxis-plugins

>- Dockerfile rules for Next.js standalone apps in a pnpm + Turborepo monorepo — multi-stage build (turbo prune → pnpm fetch/offline install → turbo build → minimal runner), pinned Node 26 Alpine by digest, checksum-verified pnpm binary, non-root uid 1001, read-only root filesystem with a writable .next/cache, HEALTHCHECK on /api/health, build args only for NEXT_PUBLIC_* values, BuildKit secrets and cache mounts, multi-arch, OCI labels and .dockerignore. Use when the repo has a Dockerfile, .dockerignore, compose file, or next.config with output "standalone", or when asked to containerise, shrink, harden or debug an image.

Nuvraxis/nuvraxis-plugins

>- GitHub Actions conventions for Nuvraxis Next.js apps — exactly three workflows: pr.yaml (every PR to any branch: Biome, stylelint, typecheck/test/build with turbo --affected, Docker build + health check, helm lint + kubeconform; publishes nothing), main.yaml (push to main: one multi-arch image to GHCR tagged sha-SHORTSHA and main, provenance + SBOM, gha cache), release.yaml (tag vX.Y.Z: verify on main, retag the existing image without rebuilding, package and push the Helm chart to OCI, GitHub Release with chart, digest and SBOM). Minimal permissions per job, GITHUB_TOKEN only, pinned action majors. Use when editing .github/workflows/*, adding a CI step, or debugging a failed run or release.

Nuvraxis/nuvraxis-plugins

>- Production rules for Next.js 16 App Router apps at Nuvraxis — Server/Client Component boundaries, Cache Components ("use cache", cacheLife, cacheTag, updateTag), Server Actions, route handlers, env handling, instrumentation, output standalone and the /api/health route. Use when the project has "next" in package.json, an app/ or src/app/ directory, next.config.ts, proxy.ts, instrumentation.ts, or files named page.tsx, layout.tsx, route.ts, loading.tsx, error.tsx.

Related Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community