Use CSR when
- You are prototyping or building an internal browser-only app.
- The initial HTML does not need server-rendered component content.
- You want the smallest setup: one HTML file, one client entry, and component modules.
Getting Started
Dathra apps are built around custom elements created withdefineComponent().
Start with CSR if you only need a browser-rendered app, or use SSR when you want the server
to emit Declarative Shadow DOM before hydration.
Choose a Rendering Path
Use SSR when
- You need usable HTML before JavaScript finishes loading.
- You want Declarative Shadow DOM output for custom elements.
- You have request-derived state such as route, locale, or user-visible flags.
CSR Quick Start
Register a custom element in JavaScript and place the tag directly in HTML. This is the simplest way to ship a client-only app.
SSR Quick Start
Render Declarative Shadow DOM on the server and hydrate the same custom element on the client.
Before You Start
- Use
jsx: "preserve"andjsxImportSource: "@dathra/core"so the Dathra transformer receives JSX. - Keep component registration explicit by importing each custom element module before its tag appears in the DOM.
- Write Dathra JSX with platform attribute names such as
classand event props such asonClick.
What Stays the Same
- Components are defined with
defineComponent() - Props are exposed as reactive signals via
props.foo.value - Styles live in Shadow DOM via
styles/css - The same custom element can be used in both CSR and SSR flows
Project Shape
The docs app in this repository follows the SSR shape: a root custom element, a server entry
that renders that element, and a client entry that registers components before calling hydrate(document).
src/DocsAppRoot.tsxdefines the root Web Componentsrc/entry-server.tsxrenders the root component to DSDsrc/entry-client.tsbinds client state and hydratesvite.config.tsinstalls the Dathra Vite plugin in SSR mode
Next Steps
After the first app runs, use the concept docs to understand the primitives behind the quick starts:
- Reactivityexplains signals, computed values, effects, and root cleanup.
- Runtimeexplains DOM insertion, text, attrs, events, SSR, and hydration primitives.
- Build Pluginexplains how Vite and other build tools run the Dathra transformer.