You’ve added a widget to a sidebar. You’ve created a section and embedded it in a page. Easy, right? That’s what every tutorial shows. But the real layout power in EmDash lives in the gap between these two systems—and most developers miss it.
EmDash widgets and sections serve distinct layout purposes. Widgets live in predefined areas (sidebars, footers) and are managed via the admin interface. Sections are reusable, component-like blocks that embed in any content type and can pull dynamic data. The non-obvious insight: sections are the path to structured content, while widgets are best for simple, static UI elements that don’t need version control.
The non-obvious insight: sections are the path to structured content, while widgets are best for simple, static UI elements that don’t need version control.
Widgets: Familiar, but Not What You Think
EmDash ships with a widget system that looks a lot like WordPress circa 2005. You define widget areas (sidebars, footer columns), then drag-and-drop widgets into them. The source material calls this “the basis of WordPress like it was 25 years ago.”
But here’s what the docs won’t say: widgets in EmDash are not sandboxed by default. If you run EmDash on the free Cloudflare tier or self-host, widgets execute in-process—same as plugins without dynamic workers. That means a poorly-coded widget can still read your database or modify files. The sandboxed plugin architecture only kicks in when you pay for Cloudflare Workers ($5/month) and explicitly use dynamic workers.
So when should you use widgets? For static, non-interactive UI elements: a copyright notice, a logo, a list of social links. Things that don’t touch the database and don’t need to be version-controlled. For anything interactive—a contact form, a login panel, a live search—use a sandboxed plugin instead, even if it seems like overkill.
Sections: The Real Layout Engine
Sections are where EmDash breaks from WordPress’s widget legacy. Think of them as reusable Astro components that you can create in two ways:
- Via the admin – Create a section in the dashboard, give it content, and insert it into any post or page using the block editor. This is the “theme builder” approach the source material praises.
- Via code – Define a section as an Astro component in your project’s file system. This gives you full version control, TypeScript typing, and the ability to inject dynamic data (e.g., “latest 3 posts”) without a plugin.
The source material shows that EmDash ships with a “sections” admin panel right next to widgets, calling them “like the theme builders.” That’s accurate—but the real power is in the code-defined sections. You can create a section that queries your D1 database for recent posts, then embed that section in multiple pages. The section’s output updates automatically when content changes.
The non-obvious tradeoff: Admin-defined sections are easy to use but locked inside the database. Code-defined sections are harder to set up (you need to know Astro) but portable across deployments and environments. If you’re building client sites, start with admin sections for content editors, then gradually migrate to code sections as you need dynamic behavior.
Widgets vs Sections vs Plugins: A Decision Framework
| Dimension | Widgets | Sections | Sandboxed Plugins |
|---|---|---|---|
| Security isolation | None (in-process) | None (in-process) | Full V8 isolate |
| Admin management | Drag-and-drop areas | Block editor insertion | Plugin install + manifest |
| Dynamic data capability | No (static HTML/JS) | Yes (via Astro components) | Yes (via hooks + workers) |
| Version control | No (database-bound) | Yes (if code-defined) | Yes (plugin code + manifest) |
| Best for | Simple, static UI elements | Repeated layout blocks | Interactive features (forms, search) |
The Practical Workflow
- Identify what’s static. Copyright text, logo, site-wide banner → widget.
- Identify what’s repeated. Header, footer, call-to-action block, “about the author” → section. Define it in code if it needs to change across environments.
- Identify what’s interactive. Contact form, comment system, analytics dashboard → sandboxed plugin. Accept the $5/month cost for the security guarantee.
- Combine them. A widget can render a section via a shortcode or Astro component. This lets you keep the widget area as the “placement layer” while the section handles the actual rendering.
The Pitfall Most Beginners Ignore
The source material says EmDash is “moving completely away from widgets.” That’s the direction—but right now, widgets are still the easiest way to put content in a sidebar. The mistake is using widgets for anything that appears on multiple pages (like a newsletter signup). That should be a section, because sections support dynamic content and version control. A widget’s content is stored in the database as plain text; a section’s content can be fetched from your content types, keeping it DRY.
When you inevitably need to change that signup form across 50 pages, you’ll thank yourself for using a section instead of 50 widget instances.
Looking Ahead
EmDash’s layout system is still in flux. The team has signaled that widgets will eventually be deprecated in favor of sections and Astro components. For now, treat widgets as a legacy compatibility layer and sections as the primary tool. The developers who adopt this mindset early will have an easier migration path when the inevitable shift happens.
- What is the main difference between EmDash widgets and sections?Widgets are static UI elements placed in predefined areas like sidebars, while sections are reusable, component-like blocks that can pull dynamic data and are version-controlled.
- When should you use a widget instead of a section in EmDash?Use widgets for simple, non-interactive elements like copyright notices or social links that don't need database access or version control.
- How can you combine widgets and sections in EmDash?A widget can render a section via a shortcode or Astro component, using the widget area as the placement layer while the section handles rendering.
