Getting Started With Scully - Angular Static Site Generator

What is Scully?

 
Scully is a static site generator for angular which helps to develop JAMStack based applications. Scully prerenders all the routes at build time and generates the static HTML and assets. 

In this blog, We will see : 
  • Scully Features
  • How it works?
  • Prerender Static Routes
  • Prerender Parameterized Routes
  • Serve static pages
Before we start exploring this, let's try to understand why we required Scully ? 
 
Normal angular application rendered on the client-side. there are some drawbacks of client-side rendered application. 
  • High FCP(First Contentful paint) time. (FCP is one of the metrics of web vitals).
    - that means the user will see the blank screen or loader until JS rendered on client-side.
  • It is not SEO-friendly as not all web crawlers can process the JS files. 
  • Performance issue in mobile and low-powered devices 
  • The application will not work if JavaScript is disabled.
This all drawbacks can be resolved with JAMStack based application. Which can be developed by using Scully with Angular.
 

Scully Features

  • Provides all JAMStack Goals
  • No efforts to integrate (It is just a layer over the angular apps)
  • Caching
  • Supports Markdown (eg. Creating Blogging Site) 
  • Provides Plugin System
  • Provides APIs to create a custom plugins.

How it works?

 
Scully adds additional power to the Angular apps. Scully prerenders all the routes at the build time and saves these prerendered HTML pages in a file system. These prerendered HTML pages can be directly hosted on any HTTP Static Server or CDN.

When any user requests the page. It will quickly give the prerendered HTML page, which will be directly visible to user. in the meantime it also downloads the angular application dist files and once that is downloaded & rendered on client-side, it will work as a normal angular application.

Prerendered HTML pages can be easily crawled by any crawlers.
 
So now let's get started with implementation.
 

Using Scully in our angular application

 
I have created a sample portfolio angular application, in which I have the following routes
  • Home page at default route ( / ) 
  • GitHub repository list page - (/github-repos)
  • GitHub repository details page (/github-repos/:repo). 
I am using GitHub public API to fetch the repository details.
 
 
 
Install Scully 

To install Scully execute the following schematic on the command prompt or terminal.
  1. ng add @scullyio/init  
This will
  • Install the @scullyio/init, @scullyio/ng-lib and @scullyio/scully package.
  • Update the polyfills.ts
  • Import the ScullyLibModule in app.module.ts
  • Add two scripts in package.json to prerender pages and serving static pages on a local server.
  • Add one sample plugin file which you can use to create a custom scully plugin.
  • Creates scully.[projectName].config.ts, In this file we will do the configuration for parameterized routes, installing a custom plugin, puppeteer launch config, output folder config etc.

Build Angular Application 


We need to build the angular application once. These build files are used by Scully to prerender the pages. 

(Note: You need to rebuild the angular app only when you do any changes in the application (like components, modules etc.), If you are doing any changes in the Scully config file, plugin, or markdown file, it is not required to rebuild angular app).
  1. ng build --prod  

Prerender the static routes 

 
We don't need to configure anything for prerendering the static routes. We just need to execute the following command on command prompt or terminal. It will list down all the routes using guess-parser and prerender it one by one.
  1. npm run scully  
 
 
As you can see above, it will skip the parameterized routes. By default, Scully prerenders the static routes, as for parameterized routes it doesn't know the value of the route param. 

This will render the pages in dist/static folder
 
Prerendered HTML Pages
 

Prerender the parameterized routes


To prerender the parameterized route we need to add configuration in scully.[projectName].config.ts file. Scully provides the JSON route plugin to fetch the route param value from API.

Scully Config for Parameterized Routes

As you can see above, to prerender all the repo details (/github-repos/:repo route) ,  I have used GitHub API which gives me the repository list and I am using name property of repository object to use it as :repo route param. You can optionally provide headers for your API call also.

Now execute npm run scully to prerender all the static and parameterized routes.
 
Scully Build Parameterized Route  
 
As you can see above, It prerenders all static routes as well as parameterized routes as HTML pages in dist/static folder.
 

Serve Prerendered Pages with Scully Serve


Execute the following command to serve prerendered HTML pages.
  1. npm run scully:serve  
 Scully Serve

This command will start the Scully static server as well as angular distribution server, You can compare the performance of both servers and see the power of Scully. You can also compare the page source on both servers, On the Scully static server you will get the whole prerendered page.
 
Great !!! We are done with the Scully implementation.
 

Summary

 
In this article, We have seen Getting started with Scully - Angular Static Site Generator. We have seen its features, how it works, its installation, and how to use it to prerender static and parameterized routes.

I hope you like this article, please provide your valuable feedback and suggestions in below comment section🙂.