1 of 24

2 of 24

Custom plugins for Scully �The Static Site Generator for Angular

Dutch Angular Group�25th of June, 2020

Sam Vloeberghs�@samvloeberghs

3 of 24

Sam Vloeberghs

Freelance Software Engineer @ Kwerri / Innovatus
Organiser of NG-BE & Angular Belgium
GDE for Angular

https://samvloeberghs.be

4 of 24

???

5 of 24

Scully - The Quick Overview

Static Site Generator (SSG) for Angular
Easy configuration
Automated Route Discovery

for static routes ( using guess-parser )
for dynamic routes ( using Scully / custom plugins )

Plugin system

6 of 24

Dynamic routes

Static Routes

Based on the Angular routing config
Auto extracted using guess-parser library included in Scully

Route Discovery Process

/ /about �/contact /users�/news /404

Based on the Scully routes config
Auto extracted / expanded using build-in and custom Router plugins

/news/update-1 /users/1�/news/update-2 /users/2

/news/update-x /users/y

Duration: 2min

Content:

The Route Discovery Process is an essential part of Scully. This is where it begins.

Because before we can prerender our pages we need to know which pages to prerender, that is obvious!

We can make a clear distinction between 2 types of routes, Static Routes and Dynamic Routes.

Static routes are typically pages that do not have a dynamic part in their url.

For example the about page or contact pages will always be those pages.

The same is true for overview pages, like news or users, their route will always be the same.

Scully can discover those routes based on the Angular Routing configuration.

The routes are auto extracted using the guess-parser library, which is included in Scully.

Opposed to that we have Dynamic routes. Those routes typically have an identifier in their path that can be used to lookup the correct data in the database or from an API.

To make those pages discoverable we need to teach Scully how to discover them. We do this by defining the routes in the Sscully config file and build custom router plugins to feed the data to Scully.

More info:

//

7 of 24

Plugin System

New ways / strategies to prerender pages
Different types:

Router

Render

FileHandler

Route Discovery Done

AllDone

Content plugins

Helper plugins

Duration: 2min

Content:

The plugin system allows you to define and configure new ways and strategies to prerender your pages.

You can teach Scully how to generate all the dynamic urls, for your most exotic routing configurations, using Router plugins.
It’s possible to extend Scully and instruct it how to process the generated output and do extra transformations, like for example minify the HTML via Render plugins
Scully is capable of handling any input source or type for the dynamic content. Think plain CSV, Markdown or any other text format. If you know how to parse it or have software to transform it into HTML, Scully can handle it via FileHandler plugins

I like to refer to these plugins as content plugins as they help us with discovering the content and processing it.

The other 2 types, RouteDiscoveryDone and AllDone, are helper plugins that we will discuss briefly at the end.�

Let’s deep dive into the possibilities of the different plugins.

More info:

https://github.com/scullyio/scully/blob/master/docs/plugins.md

8 of 24

Router Plugins

Examples:

/blog/:year/:month/:day/:slug
/news/:id/:slug
/users/:id
...

Define how to handle dynamic router parameters
Where to get the data to expand those router parameters?

9 of 24

Router plugins

Handling the dynamic route /users/:id can be done via the Scully RouteTypes.json plugin

/users/1 /users/2 /users/3�/users/4 /users/5 /users/6

/users/7 /users/8 /users/..

This will return a list of all users that are available via their dynamic url:

10 of 24

Custom Router plugins

1

2

3

Handling a more complex route like /news/:id/:slug can be done via a custom Scully router plugin:

Our route plugin gets the route and its config
Read data from the given url
Use the data to format the urls
Collect and return the full list of urls

4

11 of 24

Registering plugin

1

2

3

Before we can use our custom plugin we need to register it with Scully:

Import registerPlugin from Scully
Register the plugin with its type, identifier and pluginFunction
Export the identifier for reference

12 of 24

Configuring plugin

Importing the News constant will execute the registerPlugin in the plugin file
Associate the News plugin with the configured dynamic route
The only configuration our plugin needs is the url / data source to retrieve the news data from.

1

2

3

13 of 24

Render plugins

Examples:

Inject 3rd party scripts ( HotJar, Google Analytics, .. )
Minify HTML
Generate Table of Contents
...

Execute additional post rendering processes
Transform HTML output

14 of 24

Custom Render plugins

1

2

3

Execute your own post-processing logic on the HTML output

Define a function that transforms the HTML output
Register the plugin with its type, in this case a render plugin, identifier and pluginFunction
Export the identifier for reference

15 of 24

Configuring plugin

Importing the DemoBanner constant will execute the registerPlugin in the plugin file
Configure the DemoBanner plugin as a defaultPostRenderer, meaning it will execute for all discovered routes
This simple plugin requires no configuration

1

2

16 of 24

FileHandler plugins

Used by the internal Scully contentFolder plugin
Defines how to read specific files (and transform into HTML)
Two build-in fileHandler plugins

Markdown files
ASCII code files

“Easily” define your own

17 of 24

Generated from Markdown

18 of 24

RouteDiscoveryDone plugins

AllDone plugins

Called automatically after

all routes have been collected
all router plugins have been handled

Receive shallow copy of all discovered routes

Called after all Scully processes have finished

Duration: 2min

Content:��There are 2 other plugins available. I haven’t used them myself yet but they can have some potential for your specific project.

The first one is the

RouteDiscoveryDone:

These plugins are executed after all routes have been collected and all router plugins have been handled.

Every plugin receives a shallow copy of the array containing all the routeHandles collected during the discovery process. ��Plugins of this type can be used to calculate statistics, generate sitemaps, update the RSS feed and other things you can come up with.

The second is the

AllDone:

These plugins are called when all Scully processes and plugins have finished. Plugins of this type can be used to do some final processing or cleaning up temporary files etc. Everything that should happen at the end.

More info:

https://github.com/scullyio/scully/blob/master/docs/plugins.md

19 of 24

Community Plugins ( 1/2)

A growing set of community plugins is available

Find and list yours here: https://scully.io/docs/recommended-plugins/

Use the “scully-plugin-” prefix for naming your plugin

Makes it easy discoverable

20 of 24

Community Plugins ( 2/2)

scully-plugin-minify-html (render)
scully-plugin-disable-angular (render)
scully-plugin-sitemap (routeDiscoveryDone)
scully-plugin-toc (render)
scully-plugin-google-gtag (render)
scully-plugin-html-regex (render)
..

21 of 24

DEMO

22 of 24

Conclusion

Scully is a great tool that is still evolving
A big part of its flexibility is the plugin system

Custom ways of discovering dynamic urls
Post rendering / transformations of HTML
Handle different content file types
Post processing hooks for cleanup / additional work

Make use of community plugins

Share your own plugin

Duration: x

Content:

To conclude:

Scully is a great tool that is still evolving and it did not even officially release its first version.�It’s kinda still in a “developer” preview. But it is definitely ready to use :)�We might just expect some small and bigger updates in the future, before they officialy release.
A big part of the flexibility of Scully is because of the plugin system

It allows you to define custom ways of discovering your application routes
You can do post rendering and transformations on the output HTML
And even process different kind of text formats
Use post processing hooks, like the allDone plugin types to do cleanup or additional work at the very end.

There are several community plugins available already

And please, if you have your own, share it if you can :)

^,

More info:

//

23 of 24

24 of 24

Custom plugins for Scully

— The Static Site Generator for Angular �

@ Dutch Angular Group�25th of June, 2020

Thank you for your attention. Feel free to contact me at sam.vloeberghs@gmail.com or directly on Twitter @samvloeberghs

QUESTIONS?