Baseline** for SPA‑enabling SharePoint 2016 SE without introducing upgrade or governance debt.

SharePoint-SPA-Baseline.md

Automation Turn #6 — Best‑Practice Blueprint: SPA‑Enabling SharePoint 2016 SE (No Regression)

Scope: Introduce a Single‑Page Application (SPA) layer on a SharePoint 2016 SE site while preserving all existing content, navigation, permissions, and URLs. Constraint: SharePoint remains the source of truth; SPA is additive and removable.

---

1) Architectural Patterns (What Actually Survives Operations)

Preferred Pattern: Progressive Enhancement Overlay

• Native SharePoint page renders first.

• SPA attaches after DOM readiness.

• SharePoint retains ownership of:

  • URLs and routing truth
  • Navigation & audience trimming
  • Authentication & authorization
  • Content authoring and lifecycle

Invariant: If SPA assets fail or are disabled, the page must behave identically to native SharePoint.

Explicit Anti‑Patterns

• Client‑owned routing that replaces .aspx
• DOM‑driven SPA bootstrapping
• SPA‑side permission inference
• Rewriting master pages to “host” the app

---

2) Migration Strategy (Low Risk, High Control)

Rollout Model

• Inject SPA shell globally (inactive by default)
• Enable via route whitelist / feature flags
• Migrate by page type, never by feature

Recommended order

1. Informational / landing pages
2. Aggregations & dashboards
3. Read‑only list views
4. Forms and workflow pages (last, optional)

Rollback rule: Disable via configuration only — no redeploys, no content edits.

---

3) Routing & Navigation Preservation

• Preserve existing .aspx URLs verbatim.
• Use History API only (no hash routing).
• SPA activates only on explicitly allowed routes.
• Navigation is read at runtime from SharePoint (REST/Search).
• Respect trimming, audiences, and external links automatically.

Operational guarantee: Admins can change navigation without SPA code changes.

---

4) Data & Security Handling

• API preference: REST → Search → CSOM (fallback only)
• Normalize responses into immutable view models.
• Never duplicate permission logic in JavaScript.
• 403 / empty dataset ⇒ empty UI state (not an error).

Rule: SPA renders only what SharePoint authorizes.

---

5) CSS Integration (UI Logic Belongs Here)

Mandatory Practices

• Single, namespaced SPA root
• Attribute‑driven state (data-*, aria-*)
• No global resets or overrides
• Zero selectors targeting SharePoint markup

Regression gate: Loading SPA CSS on a non‑SPA page causes no visual change.

---

6) HTML Integration (Upgrade‑Resilient)

Rules

• Semantic landmarks only (nav, main, section, article)
• One SPA mount point
• No DOM mutation of SharePoint controls
• No DOM‑depth assumptions or wrapper “fixes”
• ARIA only for async state, not layout

Outcome: Survives master page swaps, cumulative updates, and admin edits untouched.

---

7) Failure‑Mode Guarantees

Condition	Required Behavior
SPA JS missing	Native page renders
REST timeout / denied	Module renders empty
Navigation updated	Reflected next load
SPA disabled	Zero site impact

---

8) Acceptance Checklist (Ship / No‑Ship)

• URLs unchanged and bookmarkable
• Navigation edits require no SPA code changes
• Permission behavior identical to native SharePoint
• No CSS bleed outside SPA scope
• SPA removable instantly without redeploy

---

Bottom Line

• SharePoint controls content, navigation, and security
• SPA enhances experience only
• CSS expresses UI state
• HTML remains semantic and stable
• Migration is incremental, invisible, and reversible

This is the operationally safe baseline for SPA‑enabling SharePoint 2016 SE without introducing upgrade or governance debt.