QR Code Generation | blade47/dub Wiki | doc0

Public

QR Code Generation | blade47/dub Wiki | doc0

Constant Name	Value / Mapping	Purpose
`ERROR_LEVEL_MAP`	`L` → `Ecc.LOW`, `M` → `Ecc.MEDIUM`, `Q` → `Ecc.QUARTILE`, `H` → `Ecc.HIGH`	Maps string codes to internal error correction enums
`DEFAULT_SIZE`	`128`	Default output dimension fallback in pixels
`DEFAULT_LEVEL`	`"L"`	Default error correction level specifier
`DEFAULT_BGCOLOR`	`"#FFFFFF"`	Default background color hex code
`DEFAULT_FGCOLOR`	`"#000000"`	Default foreground module color hex code
`DEFAULT_MARGIN`	`2`	Default quiet zone module width
`QR_LEVELS`	`["L", "M", "Q", "H"]`	Array of supported error correction level identifiers
`DEFAULT_IMG_SCALE`	`0.1`	Rough scale estimate for maximum allowed coverage

Design Choice	Benefit	Cost
Iterative version scanning (`minVersion` to `maxVersion`)	Automatically selects the smallest valid QR version for any payload	Increases CPU overhead for dynamic sizing on large segment arrays
Immutable module grid structure (`readonly size`, private `modules`)	Guarantees thread safety and prevents unintended mutation post-construction	Allocates new 2D boolean arrays per generated code symbol
Automatic mask evaluation (`mask = -1`)	Tests all 8 mask patterns to minimize penalty scores	Computationally intensive step during matrix finalization

Border Style Name	Path Implementation Strategy	Corner Radius / Dimensions
`square`	Sharp-cornered outer rectangle with a nested inner rectangular cutout	Outer: 7×7 at `(x, y)`, Inner: 4×4 at `(x+1, y+1)`
`rounded-square`	Rounded rectangle paths using `roundedRectPath` with continuous arc commands	Outer radius: `1.5`, Inner radius: `0.75`
`circle`	Concentric circular paths using half-arc SVG commands via `circlePath`	Outer radius: `3.5`, Inner center offset: `cx = x + 3.5`, `cy = y + 3.5`

Pipeline Function	Output Type	Logo Image Handling Strategy
`getQRAsSVGDataUri`	`Promise<string>` (Data URI)	Converts source URLs via `getBase64Image()` to inline base64 data URIs inside `<image>` tags.
`getQRAsSVG`	`JSX.Element`	Fetches base64-encoded representations via external proxy `https://wsrv.nl/?url=...&encoding=base64` and injects them into `<image>` nodes.
`QRCodeSVG`	`JSX.Element`	Supports `isOGContext` flags; switches between standard SVG `<image>` elements and absolute-positioned HTML `<img>` tags for Open Graph rendering contexts.

Parameter	Type / Schema	Default Value	Description / Validation Rule
`url`	`parseUrlSchema`	None (Required)	The target URL to generate a QR code for.
`logo`	`z.string().optional()`	`undefined`	The logo URL to embed. Restricted to paid plans on Dub.
`size`	`z.coerce.number().optional()`	`600`	The size of the QR code in pixels.
`level`	`z.enum(QR_LEVELS).optional()`	`"L"`	Error correction level (`L`, `M`, `Q`, `H`).
`fgColor`	`z.string().optional()`	`#000000`	Foreground color of the QR code in hex format.
`bgColor`	`z.string().optional()`	`#ffffff`	Background color of the QR code in hex format.
`hideLogo`	`booleanQuerySchema.optional()`	`false`	Whether to hide the logo. Restricted to paid plans.
`margin`	`z.coerce.number().optional()`	`DEFAULT_MARGIN`	Size of the margin around the QR code matrix.
`includeMargin`	`booleanQuerySchema.optional()`	`true`	Deprecated. Margin is included by default; use `margin` instead.

Design Choice	Benefit	Cost
Edge Runtime Execution (`export const runtime = "edge"`)	Ultra-low latency responses close to clients worldwide with fast cold starts.	Limited access to Node.js built-in modules and reliance on edge-compatible database clients.
Zod Schema Coercion (`z.coerce.number()`)	Automatically converts string query parameters (like `size=400`) into typed numbers.	Hides strict type mismatch errors from callers by attempting silent casting.
Centralized CORS Header Injection (`CORS_HEADERS`)	Ensures consistent cross-origin access (`Access-Control-Allow-Origin: *`) across both `GET` and `OPTIONS` preflight responses.	Exposes public generation endpoints to unrestricted embedding on external domains.

Control Name	State Property	Supported Values / Options	Purpose
Dot Style	`dotStyle`	`"square"`, `"rounded"`, `"extra-rounded"`	Controls the rendering geometry of data modules within the QR matrix.
Marker Center	`markerCenterStyle`	`"square"`, `"circle"`	Customizes the central block shape inside the three finder pattern corners.
Marker Border	`markerBorderStyle`	`"square"`, `"rounded-square"`, `"circle"`	Defines the outer border geometry surrounding each finder pattern.
Foreground Color	`fgColor`	Hex color string (e.g., `#000000`)	Sets the primary color applied to data modules and markers.
Logo Toggle	`hideLogo`	`boolean`	Determines whether the center brand logo is displayed or excavated.

// Call-chain execution for updating QR design state and preview rendering:
// setData() -> state mutation -> previewKey re-calculation -> AnimatePresence transition -> <QRCode /> re-evaluation
 
const onColorChange = useDebouncedCallback(
  (color: string) => setData((d) => ({ ...d, fgColor: color })),
  500,
);
 
const previewKey = `${data.fgColor}-${data.hideLogo}-${data.dotStyle}-${data.markerCenterStyle}-${data.markerBorderStyle}-${data.markerColor ?? ""}`;

Design Choice	Benefit	Cost
Local Storage Persistence (`useLocalStorage`)	Retains user-configured design preferences across sessions per workspace without backend round-trips.	State can become stale if workspace context or branding assets change externally.
Debounced Color Handlers (`useDebouncedCallback`)	Prevents lagging UI performance during continuous color picker dragging.	Introduces a 500ms delay before preview updates reflect color picker input values.
Memoized QR Data Computation (`useMemo`)	Avoids redundant matrix generation computations on every minor parent re-render.	Requires strict dependency tracking across all design property parameters.