HF-122: Framework integration guides for React, Angular, Vue, Svelte#1653
Open
marcin-kordas-hoc wants to merge 8 commits intodevelopfrom
Open
HF-122: Framework integration guides for React, Angular, Vue, Svelte#1653marcin-kordas-hoc wants to merge 8 commits intodevelopfrom
marcin-kordas-hoc wants to merge 8 commits intodevelopfrom
Conversation
Add idiomatic code examples to React, Angular, Vue, and Svelte integration pages showing HyperFormula initialization and reading calculated values. Each guide uses framework-specific patterns (React hooks, Angular service, Vue ref/markRaw, Svelte reactivity). Closes HF-122.
Per feedback, snippets now focus on framework-specific integration patterns (useRef/useEffect, @Injectable, markRaw/ref, Svelte reactivity) with placeholder comments for data and configuration rather than concrete values. The Demo section link is reworded from "Explore the full working example" to "For a more advanced example" to signal that the Stackblitz demo is a richer, separate project. Part of HF-122.
Expand React, Angular, Vue and Svelte integration guides to cover framework-specific concerns that the previous skeleton snippets omitted: - Convert all snippets to TypeScript with HyperFormula/CellValue imports - Add licenseKey: 'gpl-v3' to every buildFromArray call - Inline `npm install hyperformula` install command - React: runnable JSX with controlled inputs, try/catch around setCellContents, React.StrictMode note, Next.js App Router SSR section with 'use client' and dynamic import - Angular: modern standalone component + inject() + DestroyRef + Signals + OnPush, RxJS BehaviorSubject variant with AsyncPipe import note, NgZone runOutsideAngular section, provider-scope + DestroyRef rationale - Vue: <script setup lang="ts">, expanded markRaw Proxy explanation and shallowRef trap, Nuxt SSR snippet, Pinia store with updateCell action, valuesUpdated event hook, inline v-for template - Svelte: fixes memory leak by adding onDestroy(() => hf.destroy()), Svelte 5 runes primary example plus Svelte 4 delta, SvelteKit SSR warning banner and dedicated onMount section with dynamic import, wired #each template with updateCell handler
Point readers from each integration guide to related topics they are likely to need next: configuration options, basic operations (CRUD), advanced usage (multi-sheet, named expressions), and custom functions. Identical section in all four guides so the navigation experience is consistent when switching between frameworks.
The Stackblitz demo links used \${...} JavaScript template literal syntax,
which is not interpolated by VuePress. VuePress 1 processes markdown as
Vue templates, so the correct syntax for accessing the injected
\$page.buildDateURIEncoded variable is Vue's {{ ... }} interpolation.
config.js line 79 documents the intended syntax explicitly:
// inject current HF buildDate URI encoded as {{ \$page.buildDateURIEncoded }} variable
Before this fix, the cache-buster query string rendered as a literal
?v=\${\$page.buildDateURIEncoded} in the URL, breaking the cache-busting
behaviour on every Stackblitz demo link.
Note: the same issue exists in docs/guide/custom-functions.md:361 from
an earlier change; that is left for a separate fix.
Performance comparison of head (2a07790) vs base (736235e) |
…ntent) tsc smoke check found that updateCell(value: unknown) does not satisfy setCellContents which expects RawCellContent. Replace unknown with the correct type and add missing RawCellContent imports in Angular, Vue and Svelte guides.
Add framework-agnostic instruction file for AI coding assistants (Claude Code, GitHub Copilot, Cursor, Gemini CLI). Covers the core 3-operation API surface, framework integration patterns with critical rules (markRaw, onDestroy, StrictMode, DestroyRef, SSR guards), key types, common mistakes to prevent, and project structure pointers.
Collaborator
Author
Question: Automated testing for framework demos?During this PR I ran a manual tsc smoke check on all 10 code snippets extracted from the guides — found and fixed a real type bug ( This raises a broader question: should we have automated tests for the framework demos (both the guide snippets and the Stackblitz demos in The riskFramework demos can silently break when:
Currently there are no automated checks — breakage is discovered only when a user clicks a broken Stackblitz link or copy-pastes a non-compiling snippet. Options considered
Option A is lowest cost and most immediately useful — a weekly Option B catches the other direction (HF breaking demos) and could gate docs deployment. Related: demo visibility for AI toolsStackblitz links are invisible to AI coding assistants (Copilot, Cursor, Claude). AI relies solely on the inline snippets in A potential follow-up: vendoring a subset of demo code into @sequba What do you think — is option A worth setting up? Or is manual verification sufficient for now? |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1653 +/- ##
========================================
Coverage 97.19% 97.19%
========================================
Files 173 173
Lines 15013 15013
Branches 3209 3209
========================================
Hits 14592 14592
Misses 421 421 🚀 New features to boost your workflow:
|
Draft
2 tasks
Contributor
|
@marcin-kordas-hoc I need to be sure the snippets work correctly and align with each framework's best practices, so I want them to be exact code fragments from the linked Stackblitz demos. You can achieve this by either:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expand the four framework integration pages (React, Angular, Vue, Svelte) from one-line redirects into self-contained guides covering idiomatic patterns, lifecycle wiring, TypeScript, SSR caveats, and related next steps.
Design rationale
Why idiomatic patterns, not generic HyperFormula examples
Each guide answers the question specific to its framework: "Where does the HF instance live, how does it clean up, and how do computed values reach the view?" A generic
buildFromArray + console.log(getSheetValues)would not justify separate pages —basic-usage.mdalready covers that.useReffor instance,useEffectfor init+cleanup,useStatefor derived values@Injectableservice,inject(DestroyRef)for cleanup,signal()for OnPush compatmarkRawto opt out of Proxy reactivity,reffor derived values,onUnmountedcleanupconstfor instance,$staterune for reactivity,onDestroyfor cleanupWhy TypeScript everywhere
HyperFormula ships
.d.tstypings. TS snippets give readers autocomplete forbuildFromArray,setCellContents,getSheetValuesreturn types (CellValue[][]), andRawCellContentparameter constraints.Why
licenseKey: 'gpl-v3'in every snippetWithout it,
buildFromArraythrows a license warning on first run. Previous snippets had// your configuration goes herewhich hid this.Why SSR sections (Next.js, Nuxt, SvelteKit)
HyperFormula depends on browser-only APIs. The three most popular meta-frameworks all default to SSR. Without guidance, developers hit a crash on first
npm run dev.VuePress template syntax fix
Stackblitz demo links used
${$page.buildDateURIEncoded}(JS template literal syntax) which VuePress does not interpolate in markdown. Fixed to{{ $page.buildDateURIEncoded }}(Vue template syntax) matchingconfig.js:79documented intent. Note:docs/guide/custom-functions.md:361has the same pre-existing issue from PR #1621 — left for a separate fix.Simulated developer onboarding audits
Each guide was reviewed in 3 rounds by Claude Sonnet sub-agents with distinct developer personas. Round 1 also included OpenAI Codex gpt-5 reviews for React and Angular (provider diversity).
Personas tested
Round 1 verdict (pre-rewrite): ALL "No, cannot integrate in 10 min"
Critical findings:
onDestroy/hf.destroy()licenseKey→ throws on first run; no TypeScript; no SSR guidanceRound 2 verdict (post-rewrite): ALL "Yes, barely — 10-15 min"
Remaining issues found and fixed:
ChangeDetectionStrategyimportupdateCellupdateCellnot wired in templateRound 3 verdict (final): ALL "Yes, ship-ready"
Provider diversity insight (Claude Sonnet vs Codex gpt-5)
tsc smoke check
Extracted all 10 code snippets into standalone
.ts/.tsxfiles and rantsc --noEmit --strictagainst HyperFormula's own typings with minimal framework stubs.Result: 0 errors (after fixing
unknown → RawCellContentcaught by the check).Snippets tested: react-basic, react-ssr, angular-service, angular-component, angular-rxjs, vue-basic, vue-nuxt, vue-pinia, svelte-basic, svelte-ssr.
Commits
27b9582a— Initial snippets (earlier work)e920dcc3— Simplified snippets and demo-link wording (earlier work)88056b72— Modernize guides with idiomatic patterns (P0-P2 rewrite)9571737f— Add Next steps cross-linksbd84ce9c— Fix VuePress template syntax (${}→{{ }})87c2f468— FixsetCellContentstype (unknown→RawCellContent) — found by tsc smokeTest plan
npm run docs:dev) and verify all four integration pages?v=resolves to HF build dateChangeDetectionStrategyimportonMountedsnippet satisfies strict TS null-checksNote
Low Risk
Low risk documentation-only change; main risk is incorrect guidance or broken doc templating links.
Overview
Adds a new
AGENTS.mdwith shared AI-assistant guidance for working in the HyperFormula repo (core API, framework lifecycle patterns, common pitfalls, and build/test commands).Expands the React/Angular/Vue/Svelte integration pages from brief install notes into full, TypeScript-first guides showing idiomatic instance ownership, cleanup, and reactive value bridging, including framework-specific caveats (React
StrictMode, AngularDestroyRef/signals, VuemarkRaw+ troubleshooting, Svelte 5 runes +onDestroy).Documents SSR-safe patterns for meta-frameworks (Next.js, Nuxt, SvelteKit) and fixes Stackblitz demo URLs to use VuePress interpolation (
{{ $page.buildDateURIEncoded }}) so versioned links render correctly.Reviewed by Cursor Bugbot for commit 2a07790. Bugbot is set up for automated code reviews on this repo. Configure here.