PWA Starter - A Free, Online Tool to Generate the Files You Need to Update to a Progressive Web Application
Last Updated -
One of the most common requests I receive is to help businesses upgrade their websites to progressive web applications. This makes sense since I produce as much if not more content about PWAs than anyone else.
My passion around progressive web applications and helping businesses and developers succeed online has led me to create a new tool, PWA Starter. This is a free online PWA scaffolding tool to help everyone get started with their journey.
One reason why so many businesses seek out my expertise is starting a PWA journey is often confusing to less technical among us.
I have written several times as have many others what the three core technical requirements are to qualify as a progressive web app:
- Use HTTPS
- Have a Valid Web Manifest File with enough icons
- Register a service worker with a fetch event handler
To help get developers started I published a few simple games, wrote a progressive web app book, published an online PWA training course and shared a few articles along the way. For example, a trivial 15 minute upgrade of the HTML5 Boilerplate project.
These are all well and good and I invite you to go read, buy and register for all of those resources...seriously check them out!
But here's the thing...
I can write and pontificate all day long about how to build PWAs, but developers and business owner's alike are confused as to how to start with the code.
There is a lot of confusion running around about what PWAs are, how to development, etc.
Of course there are some resources out there to help get started. Some opinionated, others not so much. Some are just web manifest validators, others base service worker references or even wizards that generate icons and the core files needed.
I used all of them, many times over.
And found myself getting more and more frustrated. Many were not keeping pace; some did not work consistently and none really gave me everything I needed to get started.
On top of that controlling how and when a user is prompted to add a progressive web application to their homescreen had become a nightmare.
So I decided it was time to suck it up and create my own scaffolding tool. Something that would create an initial, valid web manifest file with all the icons you could possibly need for any consumer platform.
On top of that I also designed a tool that whips up an initial service worker and includes some additional service worker references.
But the coup de gras is an inclusion of a pre-configured Add to Homescreen library.
The Love2Dev PWA Starter is an online scaffolding tool that allows you to enter a progressive web application origin and will walk you through creating the icon set, a valid web manifest file, configured add to homescreen script and finally package it all together for download.
In less than a minute you will have an initial starter package to help guide you toward your progressive web application upgrade.
Reviewing PWA Starter
PWA Starter is a multi-step 'wizard' that collects information from you about your site. But to help out it will try to fetch your current home page and existing manifest file.
The first step is to enter your site's domain or URL in the provided field.
When you click the 'Start Your PWA Journey Now' button the tool will attempt to fetch the page's markup and any existing web manifest file. Once that process completes, even if there is no markup or manifest file you will proceed to the next step.
This step depends on the success of fetching an existing manifest file. If one can be found you will be push along to the third step, uploading an icon.
If a manifest was not found, you can either upload a manifest or move to the icon step.
To upload a manifest file, click the 'Upload Manifest' button to display a file selection dialog. Locate your local manifest file and confirm the selection. This will cause the file to be both uploaded to the cloud backing PWA Starter as well as initiate an in-memory instance you can customize a little later.
Uploading a Source Homescreen Icon
Once the manifest is uploaded or you just chose to skip along the next stop asks for a source icon. This is typically your site's logo but could be some variation of your logo suitable for a homescreen icon.
Repeat the file selection process you did to upload the manifest file.
Once you select a source icon it is uploaded to the cloud and the icons are magically rendered.
Here are some guidelines around the homescreen icon:
- I recommend a large square image
- Make sure the top left corner pixel is the color you want as the icon background
I have found square images work best. This is because some homescreen icons are rectangles, which means the generator has to assume a background color to fill in the void or be forced to skew the icon.
Skewing images is not something I recommend. So the PWA starter keeps the original aspect, but lays the icon on top of a properly sized background with a designated background color.
The icon itself will be resized, while maintaining its aspect ratio to fit the target icon's size.
Speaking of sizes, there are over 100 icons generated. They are organized by platform and saved to a 'meta' folder. I like keeping homescreen icons in a meta folder because it separates them from other site assets and concerns.
The process will also create a small set of favicon images as well, even though they are not used for homescreen icons. But as I have written before favicons are key requirements for any website to brand and ensure performance.
I mentioned background color several times, so how is this set?
For now, the process samples the top left corner pixel and uses it for the icon background color. In the future I hope to make this process better by allowing you to designate the color.
There is also a small padding added to the generated icons to account for different browsers and platforms adding rounded corners.
Personally, I have also found having a designated color is a best practice rather than a transparent background. I say this because some platforms don't honor transparent backgrounds and will fill them in with black or some other color. Plus, it seems this process is rather fluid, meaning browsers have and continue to change how background transparency is handled.
I would rather take that potential for variation out of the equation.
Configuring the Web Manifest File
At this point the PWA Starter tool is generating your icons for download, meanwhile you can customize your manifest file. This is where the manifest configuration form comes into play.
Here you can set various web manifest properties, including name, description, orientation, start URL and display mode.
The start URL will automatically appends "/?utm_source=homescreen" unless you upload your own manifest file. I do this so I have some way to track when the app is opened from the homescreen. You can use this as an example and adjust as you like. I use the UTM code because it is a standard marketing tag, recognized by most analytics tools.
If you want to know more about web manifest fields, please read my article on the web manifest file and the potential settings, or read the specification.
As you update the manifest fields, the manifest is updated and echoed to the right of the form (on desktop) so you can follow along.
You will also notice there is a skeleton web page being created as well. It is echoed in a box below the manifest file. This is another common missing component from other tools, the initial markup for your website.
The tool doesn't bother getting into the actual master layout semantics since those are all over the place. But it does generate your core HEAD elements, values and references for the supporting assets.
You can use this as a base to build your site's themes and core layouts.
Oh boy, we have done a lot by this point. But wait, there's more!!!
Configuring the Add to Homescreen Library
If nothing else, this step separates the PWA Starter apart from other tools, the Add to Homescreen library. This of course is a library I forked and upgraded recently. Originally created by Matteo Spinnelli to help automate the iOS add to homescreen experience almost a decade ago, he had abandoned the solution a few years ago.
I decided to fork the library and update it to handle the modern progressive web application add to homecreen landscape.
I wont go into details about the library here because I have resources for it on the Github page and this site.
Like customizing the web manifest file, PWA Starter helps you configure the library to meet your requirements.
Just like the manifest panel, you will see the configuration echoed in a box to the right.
Downloading The Final PWA Starter Package
Now that you have entered everything the last step is to download your final package. The last panel includes a download button and a list of the included assets.
The actual zip file may take a moment to create, so the button will tease you with a spinner, I mean how else would a site make you wait!
Once the file is ready the button will display, Download, at this point just click the button and your file will start to download.
The generated content and zip file will be available for about 24 hours. I have an automated clean up process that triggers every night to purge stale packages. So, don't let them sit around too long.
Don't worry you can always come back and generate the package again. Remember this is a free tool.
Start Your Journey Now
Now that you have seen how to use PWA Starter and what it can do to help you upgrade your site to a progressive web app I invite you to try it out.
Even if you already have a progressive web application there is a good chance it give you something that can make it better. If nothing else it seems like the add to install experience, web manifest or icons are changing each month.
Because this tool is something, I created to help me scale my business it will continue to be updated as fast as I can react to PWA experience changes across platforms.