Every other week, the Principle Studios Engineering team gets together and talks about relevant topics in the industry. Sometimes we have a group discussion on current events, sometimes we have multiple presenters showing small development technique improvements… and sometimes we have one larger presentation that takes most of the time.
This meeting had a single larger presentation: we went in-depth into the new PrincipleStudios.com site architecture.
High-level Architecture
Matt DeKrey began the presentation by discussing the decision factors behind the new architecture. The new PrincipleStudios.com site is built using AstroJS. We evaluated many options, including NextJS, Gatsby, and several other site generators. Ultimately, we liked the concept of Astro Islands and the flexibility they provide for working with other frameworks, as well as the significant decrease in client-side JavaScript. Built-in support for React was a must, but the flexibility to work with other frameworks in the future is ideal for a consulting company like ourselves - we want to be able to showcase any work we can in the future.
As a side note, the old site was built in Gatsby. Unfortunately, while the volume of integrations made Gatsby look quite appetizing at first, working with it with even basic React libraries was a bit of a chore, and most integrations were sorely out of date.
As a further positve note on AstroJS, first-class support of MDX was important to us for quickly writing blog posts in a standardized way; even this article is written using simple Markdown.
There were a handful of other technologies we used, including Astro’s Asset extension, sharp for image resizing and formatting, and TailwindCSS for adhering to a styleguide.
Finally, for hosting, we’re running the site via Azure Kubernetes Service, which allowed us to spin up sites per PR for visual testing of the changes. When making updates to a grid layout or our Tailwind configuration, it’s just easier to visually check to see if the PR did the right thing.
Project Layout
Kris Henderson led the next section talking about the organization of the source code. Our basic directory layout is as follows:
/adrs/- Architectural Decision Records are a process we have begun to adopt for our projects, specifically to document “why”./deployment/- A handful of scripts for deployment, including rotating security credentials and values for Helm charts./docs/- A location for documentation that should be kept up-to-date for how to perform various tasks within the project./ui/public/- Astro’s standard folder of static files to copy to the output. We decided to keep images with the components that use them, so this folder only has our favicon in it./ui/scripts/- A set of scripts to be used when rendering the content - but not content files itself./ui/src/components- Components intended for reuse across multiple pages./ui/src/config- A common location for configuration settings, such as what email addresses to use across the site./ui/src/content- Astro’s “content” folder, used for blog posts, case-studies, and several other dynamic pieces of data across the site./ui/src/pages- Astro’s file-based URL structure./ui/src/page-components- We didn’t like the convention of prefixing page-specific components within the “pages” folder - it was unclear what components were used for which page, and also made it unclear which files generated actual pages when paired with parameterized files, so we put single-page components in a parallel folder structure./ui/src/styles- A collection of reusable style definitions that are too common to be truly componentized./ui/src/utils- A handful of reusable utility functions, such as detectingisSSRor detecting resizes of an HTML element.
Kris also explained to the team more thoroughly how the PR review site worked, with a GitHub Action to set up the PR site when the PR is opened or updated, and another GitHub Action used to clean up those resources once the PR was closed or merged. A separate Azure DevOps pipeline handles production deployment, allowing the site stakeholders to review the staging site then approve deploy to production without leaving Slack.
Cool Features
Seth O’Harra was the final presenter for this team meeting, showcasing some of the cool features on the site.
- The video on the home page uses an image mask to blend in with the background to guarantee that various OS color spaces don’t conflict. Without the mask, the actual box around the video could be visible, depending on your OS. Thanks goes to Megan Kossa for finding this clever solution!
- Our Principle logo is transparent, allowing the colors of what it’s on to show through, just like our company allows the colors of our clients to shine through our work. On a light-colored background, we swap the color of the logo to a dark version.
- We generate custom responsive images - up to 39 for the Astronaut component on the home page - that support various device pixel densities, image formats, and all our breakpoints for a carefully-curated full-width image (up to a very large screen size, at least.)
- At launch, we have both Lottie and Rive animations on the site. Again, thanks goes to Megan Kossa for building a Lottie proof-of-concept that worked in React and AstroJS!
- The menu navigation communicates across Astro Islands using a tiny state library called Jotai.
Full team callout
Since this was our launch announcement (a few days early, we were excited, who can blame us?) to the engineering team, we had to give a full-team shout-out to everyone who worked on the new site, too:
- Strategy/Creative/UX – Mary Kate Maltzan, Drew Nowacoski, Tyler Cutforth, Charles Triponez, Gloria Rafeld
- Engineers – Matt DeKrey, Seth O’Harra, Megan Kossa, Kris Henderson, Ahmed Rezk, Zachary Banducci, Michael Geise
- QA – Shelly Brill, Katelyn Dallmann
- PM – Carrie Coey, Shelly Brill, Jess Reid
- Direction/Input/Review – Adam Brill, Adam Powell, Daniel Andresen
Thanks to our presenters!
Again, thanks to Kris Henderson and Seth O’Harra for presenting this week. Megan Kossa unfortunately had lost her voice due to illness earlier that week that hadn’t returned; she was looking forward to showcasing a number of features herself.
We always appreciate seeing the work that our team does and geeking out over the details of software engineering; we won’t be able to share what we discussed on our blog every week, but we hope you enjoy reading what we can share!