The brand site needs crawlable, compliant narrative; the dApp needs connect and upgrade paths—one repo, one domain often fails both
Many Web3 teams cram whitepaper, team, fundraising narrative, and Connect Wallet into one Next app—then learn marketing wants daily copy while contracts and ABIs want frozen releases; SEO wants static crawlables while the dApp wants client wallets and RPCs; a PR incident needs a sitewide banner while on-chain features cannot casually go dark. On blockchain and web work, KSX separates brand site and dApp shell in IA and release pipelines, then shares design system and components—institutional trust sites prioritize clarity; product shells serve transactions and read-only chain state. The split is not architecture theater; it gives compliant narrative, performance budgets, and wallet sessions their own lifecycles. Below: decision criteria, topologies, share boundaries, and anti-patterns.
Start with who changes what, how often
Change rate is the first split signal. Brand site: campaigns, careers, press, legal copy, locales—editorial and marketing led, preview and rollback in hours. dApp shell: feature routes, wallet connect, contract read/write facades, errors and chain switch—engineering led, releases tied to audited contract versions. One train either blocks marketing on eng or lets hot copy ride with chain-touching deploys. In discovery, list what actually merged last week; it beats an idealized monolith diagram.
Preferred topology: content domain + app subdomain (or proxied path)
A durable pattern: `www`/apex for brand (SSG/ISR-friendly), `app.` or `dapp.` for the walleted shell. Path-based `/app` works if you carefully isolate cookies, CSP, and cache—easy to cross-contaminate. Brand CTAs “Launch app” jump to the shell with UTM; the shell links Docs/About back to the brand site so you do not fork a second SEO corpus inside the app. If China and global traffic split, lock domains and hosting regions in discovery—not the week before launch DNS panic.
SEO and crawlability: wallet pages are not your homepage
The brand site owns indexation, story, and trust: team, partners, audit summaries, sober product copy. Default the dApp shell to `noindex` or index only static docs—not empty “Connect Wallet” shells in the SERP. Structured data, hreflang, case studies, and blog live on the brand site. If marketing shows on-chain stats (TVL, latest block), use cached read-only APIs—do not drag a full wallet stack onto the homepage for a number.
Keep wallet and session boundaries inside the shell
Connect, sign, network switch, and account listeners stay in the dApp shell. The brand site may list supported networks/wallets and safety tips—never auto-prompt connect on a landing page. That reduces accidental connects and focuses anti-phishing education on the app origin. In-shell onboarding: understand the action before sign; human-readable summaries; actionable errors for chain, balance, and permissions. Many Web3 visitors are not crypto-native—trust narrative on an institutional site and wallet guidance in product may share audience but not mindset stage.
Decouple security headers, dependencies, and release cadence
The shell’s CSP, wallet deps, RPC, and ABI pins need stricter change review; the brand site often adds CMS, forms, and pixels. Separate repos or at least pipelines so a marketing pixel does not relax shell CSP. Contract upgrades and ABI bumps follow a checklist; brand emergency banners must ship independently. Secrets: shell RPC keys and wallet project IDs must never land in static marketing build artifacts.
Anti-patterns: fake splits and over-splits
Fake split: subdomain still one build, one aggressive cache policy, one big-bang release. Over-split: wholly different components and tone so the jump from site to app feels like phishing. Another trap: iframe the dApp inside the brand site—sessions, responsive layout, and headers all get harder. Early teams may start monolithic, but draw module boundaries and code-split marketing vs wallet routes, feature flags, and the stage-two split triggers (DAU, compliance, editor count) in writing.
A decision list aligned with the KSX process
Discover: audiences (investors/users/regulatory narrative), which actions must be on-chain, content cadence, hosting and regions. Design: two sitemaps, shared tokens, path from CTA to first signature. Build: separate pipelines, env boundaries, cached read-only chain data on marketing pages. Launch: separate perf and security checklists—brand site leans Core Web Vitals and SEO; shell leans wallet failure rate and RPC degrade. When you want one delivery team, KSX can still run two release tracks—not pretend one repo solves every political constraint.
Checklist
- 1Use change rate and owners to decide if brand site and dApp share one release train
- 2Define domain/path topology, noindex policy, and cross-site CTAs/backlinks
- 3Wallet connect/sign only in shell; no auto-connect on marketing pages
- 4Share design tokens and analytics names; split pipelines, CSP, and secret boundaries
- 5Prepare independent release paths for contract/ABI bumps and emergency brand banners
Key takeaways
- Splitting Web3 brand site vs dApp shell is about different change lifecycles and risk models—not looking advanced.
- SEO and trust narrative on the brand site; wallet session and contract coupling in the shell; glue with a design system.
- Fake splits and iframe nesting tax security and UX; boundaries belong on the release checklist.
FAQ
- Should tiny landing-only projects split too?
- Not necessarily separate domains day one. Still code-split marketing vs wallet routes and write split triggers (editors, audit version, regional compliance). Drawing boundaries early is cheaper than a forced migration.
- Is documentation part of the brand site or the shell?
- Protocol/API docs for developers often live on `docs.`; end-user help can sit on the brand site. Step help tightly bound to a transaction may stay in-shell—avoid three stale copies of the same article.
- Can the brand site show live on-chain data?
- Yes—via read-only indexers or cached backends with TTL and degrade placeholders, no wallet dependency. Treat numbers as narrative aids with “as of” timestamps, not as a trading UI.