Getting Started with Analog

To begin your journey with Analog, ensure that both Angular and Node are installed on your system. You can initiate a new Analog project by executing the following command:

npm create analog@latest

Keep in mind that Analog leverages Nx internally, which provides the benefits of Nx caching. Initially, the setup may not resemble a typical Nx project due to the absence of an nx.json file and the usual apps and libs directory structure; instead, it establishes what is known as a standalone application.

For those who wish to harness the full capabilities of a comprehensive monorepo with multiple libraries and applications, the following command can be run:

npx create-nx-workspace@latest --preset=@analogjs/platform

Alternatively, you can incorporate an Analog project into an existing Nx workspace with:

npm install @analogjs/platform --save-dev

npx nx g @analogjs/platform:app analog-app

SSR and File-Based Routing

To optimize SEO and enhance initial performance, Analog employs SSR. Unlike traditional Angular applications, where the initial page loads client-side, Analog renders the first page on the server and sends the fully formed HTML to the client. This allows for immediate display without waiting for JavaScript to load.

The server and client codebases are identical, which simplifies maintenance and understanding. However, caution is necessary regarding the code context; server-side code lacks access to the DOM and window object, which are available on the client side. Adapting to this different mental model is essential for effective SSR development.

Next, let’s explore file-based routing. Forget about Angular's loadChildren and loadComponent methods; Analog primarily utilizes Angular's router. The routing mechanism in Analog resembles that of Next.js and Nuxt, where the file path of a component directly corresponds to the page route.

For instance, creating a file named src/pages/about.page.ts will yield a page route of /about. Similarly, a file at src/pages/blog/[slug].ts will correspond to the route /blog/:slug. This file-path-to-route correlation enhances clarity in application structure.

You can also implement layout pages that utilize router-outlet to provide a cohesive layout for child routes. To achieve this, create a page component that shares the name of the route fragment, effectively organizing your application's layout.

Additionally, you can define metadata for a page by declaring a constant of type RouteMeta within your component file:

export const routeMeta: RouteMeta = {

title: 'My Title'

};

While there are additional considerations for query parameters, indexes, and redirects, it is advisable to refer to the documentation for comprehensive guidance.

Static Site Generation and Content Routes

If you aspire to establish a blog, leveraging static site generation (SSG) to transform markdown files into static pages is beneficial. Many SSG libraries exist, such as Gatsby and Astro, but Analog natively supports SSG.

To enable content routes for markdown rendering, include the following in your application configuration:

import { ApplicationConfig } from '@angular/core';

import { provideContent, withMarkdownRenderer } from '@analogjs/content';

export const appConfig: ApplicationConfig = {

providers: [

// ...

provideContent(withMarkdownRenderer()),

],

};

You are now equipped to create content routes. For instance, placing a markdown file at src/page/content.md will render its contents as HTML at localhost:4200/content.

Moreover, you can employ front-matter to specify metadata that won't be rendered, such as blog post titles, authors, or publication dates:

title: Module Boundaries in Nx

date: 2023-11-06

articleSeries: Modularization

slug: module-boundaries-in-nx

tags: [angular]

description: lorem ipsum

It's advisable to consolidate all blog posts within a single content directory, allowing you to load them collectively for an overview page. This requires defining an interface that matches the front-matter data structure:

export interface BlogPost {

title: string;

date: Date;

articleSeries: string | null;

description: string;

coverImage: string;

tags: ('angular' | 'react' | 'vue' | 'javascript' | 'nx')[];

}

You can utilize the injectContentFiles function to retrieve all blog posts easily:

readonly posts = injectContentFiles();

This function will return the contents as ContentFile[], allowing access to metadata defined in the front-matter via the attributes property.

Opting for Client-Side Rendering (CSR)

Despite the advantages of SSR and SSG, there are scenarios where client-side rendering (CSR) is preferable. This might apply if you need to access the Document or Window objects or when dealing with an admin panel that doesn't require SSR.

While Analog does not natively support CSR configuration for specific routes, you can implement a workaround to disable SSR for certain routes:

// main.server.ts

export default async function render(url: string, document: string) {

// Client-render any admin URLs

if (url.includes('admin')) {

return Promise.resolve(document);

}

// Server-render anything not prerendered

const html = await renderApplication(bootstrap, {

document,

url,

});

return html;

}