Useful Tips for Debugging with Scully

So you're excited to pre-render your application pages and want to use Scully to do it. Yay! But you're getting frustrated because you're not getting helpful errors and the documentation isn't as robust as you'd like - we've all been there. Check out a few of my tips for debugging projects implementing Scully.

Basic Scully Debugging Tips

1. Join the Scully Gitter channel, and search for your issue to see if it's come up in the chat previously.

2. Watch the Scully repo to get updates on issues and their resolutions.

3. Save up your Scully questions and join the Scully Office hours, every Tuesday at 12:00PM Mountain time.

Scully is still a very new tool for the Angular community, and the brilliant creators behind it have full time jobs beyond supporting this project. The creators are very gracious with their time, and I've spent more than a few hours bothering Sander with issues I've run into, so I wanted to share some SUPER pro tips I learned from him.

PRO Scully Debugging Tips

1. Clone the Scully repo

I find it way easier to solve my issues or figure out what a config option should look like by having the repo open in VS Code and being able to quickly click through interfaces or do global searches.

2. Do incremental renders in Scully to test just the routes you're working with.

When you're working with dynamic routes, you may be creating and rendering hundreds of pages, which takes time. If you're writing a custom plugin and want to focus on just the routes using that plugin OR there's just one part of your Angular app that you need pages rendered for, there's a flag for that!

You can only render the routes you care about by using the baseFilter flag

npm run scully -- --baseFilter=/my-route

3. Understand HOW Scully is rendering the pages.

Under the hood, Scully boots up Puppeteer which serves the app you've compiled to the dist/your-project-name directory, and crawls those pages to copy the markup.

4. See what Scully sees when rendering your pages.

You can use the showBrowser flag to have Puppeteer launch the Chromium browser so you can see what's going on. This can be helpful if you think a JS error is blocking the page from loading, an http request might be failing, or ensuring your proxy file is working correctly (if you're using one).

npm run scully -- --showBrowser

5. Debug any potential issues with your Angular router code

When implementing Scully for a client recently, Scully would build the index.html page for the base path of the application, and then stop, no errors, no warnings. Scully uses the library GuessParser to determine the routes written in your Angular application.

You can use the showGuessError flag to show any errors that GuessParse throws.

When I ran

npm run scully -- --showGuessError

I was able to see the error about myGroupOfRoutes from GuessParser and tracked down the source - the original application routing code was trying to use the spread operator to create route arrays (ps, this isn't supported and probably won't be any time soon so don't do it!)

GuessParser cannot interpret the routes in this code:

const myGroupOfRoutes: Routes = [
    {
        path: 'home',
        component: HomeComponent,
    },
    {
        path: 'about',
        component: AboutComponent,
    }
];

const myOtherGroupOfRoutes: Routes = [
    {
        path: 'items',
        component: ItemsComponent,
    },
    {
        path: 'items/:id',
        component: ItemComponent,
    }
];

const routes: Routes = [
    {
        path: '',
        children: [
            ...myGroupOfRoutes,
            ...myOtherGroupOfRoutes,
            {
                path: '**',
                redirectTo: 'home',
                pathMatch: 'full'
            },
        ]
    },
];
export const routing: ModuleWithProviders = RouterModule.forRoot(routes);

I hope this helps you get Scully implemented in your project more quickly! Do you need help with Scully, pre-rendering Angular pages, or improving Angular application performance in general? Leave a note in the comments or shoot me an email!