angulardart_prerender library

Prerendering tool for AngularDart applications.

This library provides a standalone script that generates static HTML files for each configured route using a headless browser (Puppeteer).

Quick Start

  1. Add the dependency to your pubspec.yaml:
dev_dependencies:
  angulardart_prerender: ^1.0.0
  1. Create a prerender.yaml configuration file:
routes:
  - /
  - /about
  - /contact

exclude:
  - /admin/**
  - /dashboard/**

timeout: 5000
wait_for_selector: '[data-prerender-ready]'
wait_for_network_idle: true
generate_sitemap: true
generate_robots: true
base_url: 'https://example.com'
  1. Build your app:
dart run build_runner build --release
  1. Run the prerenderer:
dart run angulardart_prerender

Configuration

Routes

You can specify routes in two ways:

  1. Static routes: Simple path strings

    routes:
  - /
  - /about
  - /contact

  2. Dynamic routes with providers: For routes with parameters

    routes:
  - path: /blog/:slug
    provider: routes/blog_routes.dart#blogRoutes

  3. Excluded routes: Routes to skip

    exclude:
  - /admin/**
  - /dashboard/**

Rendering Options

  • timeout: Maximum time to wait for a page to render (ms)
  • wait_for_selector: CSS selector to wait for before capturing
  • wait_for_network_idle: Wait for network requests to complete
  • viewport_width: Browser viewport width
  • viewport_height: Browser viewport height

Output Options

  • generate_sitemap: Generate sitemap.xml (default: true)
  • generate_robots: Generate robots.txt (default: true)
  • base_url: Base URL for canonical URLs and sitemap

Dynamic Routes

For routes with parameters (e.g., /blog/:slug), you need to provide a list of concrete routes. Create a provider function:

// routes/blog_routes.dart
List<String> blogRoutes() => [
  '/blog/getting-started',
  '/blog/advanced-tips',
  '/blog/best-practices',
];

Then reference it in your configuration:

routes:
  - path: /blog/:slug
    provider: routes/blog_routes.dart#blogRoutes

Component-Level Control

You can control prerendering at the component level:

Exclude a Component

@Component(...)
@NoPrerender(reason: 'Requires authentication')
class AdminDashboardComponent {}

Configure Prerendering

@Component(...)
@PrerenderConfig(
  waitForSelector: '[data-content-loaded]',
  timeout: 10000,
)
class BlogPostComponent {}

Dynamic Control

@Component(...)
class ProductComponent implements PrerenderAware {
  @override
  bool shouldPrerender() => /* your logic */;

  @override
  PrerenderConfig get prerenderConfig => PrerenderConfig(
    waitForSelector: '[data-product-loaded]',
  );
}

Sitemap and Robots

The prerenderer automatically generates:

  • sitemap.xml: List of all prerendered URLs
  • robots.txt: Points to the sitemap

You can customize these in the configuration:

generate_sitemap: true
generate_robots: true
base_url: 'https://example.com'

Troubleshooting

Browser not found

If Puppeteer can't find a browser, install Chromium:

# On Ubuntu/Debian
sudo apt-get install chromium-browser

# On macOS
brew install chromium

Or specify the browser path:

browser_executable_path: '/usr/bin/chromium'

Timeout errors

Increase the timeout:

timeout: 10000

Blank pages

Make sure to wait for your content:

wait_for_selector: '[data-content-loaded]'

Or add the attribute to your component:

<div data-content-loaded *ngIf="dataLoaded">
  <!-- content -->
</div>

Classes

HtmlRenderer
Renders HTML pages using a headless browser (Puppeteer).
NoPrerender
Annotation to exclude a component from prerendering.
PrerenderAware
Interface for components that are aware of prerendering.
PrerenderConfig
Configuration for the prerendering process.
PrerenderData
Annotation to mark a route as requiring dynamic data for prerendering.
PrerenderOptions
Annotation to configure prerendering for a component.
RouteCollector
Collects routes to prerender from configuration.
RouteConfig
Configuration for a single route.
RouteProvider
Annotation to specify a route provider for dynamic routes.
SitemapGenerator
Generates sitemap.xml and robots.txt files for SEO.

Extensions

SitemapRoutes on List<String>
Extension methods for sitemap generation.