GitLab Digital Experience, 30 Aug 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Core Marketing Site - Javier Garcia and Tyler Williams

Description

Javier Garcia and Tyler Williams discuss the Nuxt.js repository for GitLab's Core Marketing Site. A freeform conversation that starts at a high level and explores the Slippers UI integration, build processes, and CI pipeline configuration.

Core Marketing Site handbook page: https://about.gitlab.com/handbook/marketing/inbound-marketing/digital-experience/marketing-site-rearchitecture-project/

Core Marketing Site repository: https://gitlab.com/gitlab-com/marketing/core-marketing-site

Slippers UI: https://gitlab.com/gitlab-com/marketing/inbound-marketing/slippers-ui

A

Hey hello, um it is monday august 30th of 2021 uh javi, and I are going to talk about the new uh core marketing website for from the digital experience team. uh Perhaps team name to be changed. Who knows uh yeah? um We don't have an agenda for this. I'm gonna try and keep it like to the point and try not to like ramble too much. There's a lot of stuff going on. We haven't pulled up an agenda. This is a little informal.

A

I don't want to make it too long, but um I don't know let's, let's find what's useful. um I'm gonna share my screen and just sort of like drive around and show like what we got going on. um So this is the core marketing site. uh You know as a public repository as most of our projects are um and I'll drop a link to it, or we have a handbook link to it, um which is also in the uh repository here. um So at its core. uh It is a next site.

A

um So next is like a framework for writing. Vue.Js provides utilities to build either like single page applications, server-side rendering applications or, in our case statically generated websites um and uh we've enabled typescript support. uh Something that's good to know is that so typescript support is enabled it is preferred, um but you can opt out of it, for if you have reasons um so there are some things like in particular, um I have one actually more than one.

A

I have a couple of um plugins that we need to use that are written as just plain javascript files, because it makes more sense to keep their third-party integrations and instead of spending the time to convert the third-party integration to typescript and then in the process of that deviating from the third party like happy path. I'd rather just keep things as they are, so the nice thing is, you don't have to write typescript.

A

So, if you're coming to this uh from a non-typescript background, you can still be productive and I think we should, as as much as possible, prefer typescript uh it you know, will prevent us from making author time mistakes, as you know more so than if we didn't use it. It'll also provide convenient, um uh just code, completion, stuff and other tooling there so where you can write typescript if you're writing javascript, but you do have an escape hatch.

A

If you need to get something done and you don't want to, you know, learn typescript to do the one quick thing you need to have done or if there's a good reason like a third-party integration that doesn't have type trip support, so um so yeah, that's sort of the the top level. Here, um we've got a oops sorry, I didn't mean to expand that um we have uh like a gitlab pages site specifically for this um you'll notice, actually that um the root- so maybe here's another good thing to talk about, is like.

A

The this is supposed to be: it's not a full drop in replacement for the existing marketing site at about.getlab.com.

A

It is a supplemental website and it would be like almost like if we were building a mono repo, but for technical reasons like amano repo doesn't solve our problems, um but the current middleman sites all deploy to the same google cloud, storage, container, right and they're just and we just have routing, set up for them through pastly, so um the nice thing is anything can deploy to it as long as it has the right keys.

A

So this is just another repository that has its own ecosystem that deploys to the same google cloud bucket because like it can because it's a statically generated website. So, at the end of the day it compiles down to html, css and javascript and, like you just not just but like you, can put it on any static file, server and it'll work. So it gives us a lot of options and flexibility.

A

um So the reason I said that is, uh you can go to the uh the pages deployment of it, um but we don't build index.html because we're not yet ready to be serving the homepage from this. So right now I have a test page, which you can see here. Instead, so um can I expand this yeah um so yeah? This is like the test space. You have to go to like slash test page as we build more pages they'll become available here. This is not meant to be like a.

A

It exists. As a reference point. It's like hey. You know we build something to somewhere, but it's not really meant to be like a particularly useful tool. We do actually have um review applications set up for it um and here let me look at a merge request. uh Let's find a merged one uh review app yeah. This will do it, um so you can actually go to so now when you make mrs uh oh, it might be gone because this is an older branch.

A

I did this a while ago, so we have review apps, enabled and it'll review. Whatever changes you made um so I'll, stop there that's a lot, but there's plenty more to talk about um javi. Do you have specific questions starting? Yes,.

B

I do I have one of the questions in particular. Okay- and I think it was kind of like primed by like something I had in mind- is that I built a footer component with slippers as and it's essentially using view purely based on templating, I'm not using it for any sort of like I'm, not using it. Like a view. Life cycle at any point would a setup that we have here. Just statically render a footer yep.

A

Precisely and that's what it's doing in um so I'll talk about two things about one, the integration and then two what's actually happening. um So uh a note um we're doing docs in this docs folder. uh If you go to the readme, there is a note about it, gitlab documentation. So a lot of the readme is just the boilerplate next readme and I want to just keep it there as much as possible like and until it makes sense for us to deviate from the convention. I will stick to the convention, but we do.

A

I did want more detailed places to put notes about what's going on and decisions. Basically, my rubric here is, if I am making a change to the website. That is not the standard next configuration.

A

I have to write a note about it and why I made that change right like like, if I made a decision that next didn't make for me, I go right about that decision. So people understand that I that it was made right- and I think other folks should follow that same. It's that same kind of approach. um You know as much as generally.

B

A

Yeah um so uh so, there's a docs, folder docs and there's a slippers, ui folder, so uh there's a link to the slippers, ui repository uh and we use typescript, um and so there's a note about. uh We have a declaration file that basically says hey. This is a module um and it unless it's handy when we're talking to typescript, we can say: hey this library doesn't have typings, don't worry about it, just hand wave it away. Just it's it's nothing!

A

It's it's, it's a module, um and so we pull it in uh and we pull it in as a plug-in uh where, basically we do if you've seen what we've done on the middleman site, we do kind of the same thing where we um grab slippers components from our package and then we register each component from slippers ui as a component. Here right. We just register it to view there's some documentation on what plugins are and how they work at next. But basically, nux is a layer.

A

That's kind of on top of you. Nux says, like a framework, has its own view. Instance. It's like hey, like, I know what vue.js the library is, and we have these opportunities and plugins to like modify that instance of vue.js, and so that's what we're doing here and we modify vue.js so now, vue.js knows about slippers, ui components, it's just built into our instance of view, which next is hooking into here. So it's like hey. If I call slp navigation, I know what a component is right.

A

um We also in our config file, because slippers ui comes with its own styles. We can we actually tell next that it should grab those styles as well. So we grab that here right um and then to answer your question specifically. So that's how slippers is like integrated is like it's installed as a package installed as a plug-in configured to grab any of the assets we need from it. um We could do the same even with images. If we included them, um we shouldn't, but we could.

A

um Then you can just uh sorry I try not to say yes, then you can use um components from slippers ui as though they are as though they are um built-in components to next. So this is our layout file. We have one default layout right now: it's just top level layouts default.view, you use for layout files and pages use view single file components.

A

This layout gets wrapped around everything. So you'll see this nux component is like a custom, nux component. That basically says whatever nux is doing put it inside here, but we're wrapping it in like a little container div and we and I dropped slp navigation, which is the slp navigation component. Here at the top and now you'll see here, here's our uh component, oh, I think I actually need to.

A

We need to wire up a little event listener on that button, because it's not built into the component itself you'll see. Here, though, uh the navigation is working right. This is rendered statically.

A

um So when we generate the all of these things you can get in next is clever, and it will actually tell you if it leaves breadcrumbs for itself, so I think you can actually go into. Oh, maybe.

B

Not you developer tools, maybe.

A

Oh, you can't with a static site anymore. Okay, that's great, um but that's good, because this is all just statically generated. This is exactly what we want it to be. um It's not a view component, it's not rendering client-side, it is statically generated, and it's dr oh. I know why um this is the build. This is the production build which does.

B

A

I think the development.

B

A

Yeah locally, if I do uh yarn dev.

A

I think in this instance slash tests page once it boots up yeah. I think in this instance. It actually makes that available to me. So this is exactly like a good thing to show. It's like there is um because.

B

It would be a view component right.

A

Yes and there yeah there, you have it, so you can actually.

B

A

um So what will happen is in in development mode. When you run yarn, dev is the command I ran here. It will render it as the server's the server rendering version.

A

If you wanted to check out what the statically built one would be, it would be, you would run yarn generate so, and this will be good for debugging. So, like keep in mind, if you're just doing yarn dev, you are in a very different environment or a slightly different environment than the production build will be in.

A

If you run yarn, generate you'll, get a production, build or you'll get a you'll get a static, build that is similar to um the production, build, although it'll be from the development environment, so it might be a little different it'll go to this dist folder, which is somewhat conventional, and then, if you wanted to serve it, so you could do like npx http server, uh dist right.

A

um And that's just um I just ran.

B

A

A little local server for folks who haven't used it before, and here we are um there's no index page right, like I said so, we're just getting the plane. But here's like a test page here we are and then here you'll see. This should look uh yeah, there's no view dev tools here, and this should look exactly like this. So if you want to see the static build, you do have to take an egg.

A

You have to go a different route than the development, but if you, but generally speaking, you don't want to do this because this doesn't have like hot reloading like it doesn't have all the nice of these. You don't get the view tools.

A

If you want the view tools, um you should run yarn depth and that that's going to be the the the best developer experience when you're working locally on the site, um but if you've run into bugs that you're, not precisely like, if you get a bug in production that you're not seeing in development, one of the first things I would do is I would go check out the statically generated version of it locally and see if that helps like clear up any confusions, because um again answering your question.

A

If we just dropped slp footer into this layout file, I have the zoom tools up here. So I can't see it perfectly.

B

A

Into the layout file, if we dropped what.

B

Why don't we try it? I'm kind of curious, oh.

A

Is it in there I, I haven't updated the version of.

B

A

B

See if it'll work yeah, because I might have not included it like since it's only yeah, I think I need to include like in the main.js. It needs to be included in there.

A

Yes, it does um have you done that in a different version of slippers,.

B

No, I have no okay.

A

Cool, so so there's no way for us to get it, um but what we could do is um we can run yarn, upgrade slippers ui to get the latest or you could do yarn upgrade at a specific version. Well,.

B

Actually, let me check, I actually I answered that and I'm actually not sure, but I would, I would think, no like if it fights a guess.

A

Here I'll upgrade slippers ui here, let's find out. This is a good demonstration of like what what, if you need to upgrade to a slippers version or if you need to pin it to a specific one, use the yarn tools for it, because it's installed as a yarn package.

B

Yeah, I don't think so, though, now that I think because I haven't touched that at all. So if you.

A

B

Might not be there yeah. I I.

A

Haven't done it, so um I don't think we'll actually end up getting it. Even if we get this most recent version of slippery's ui but yeah, uh the answer is, uh it will become statically rendered. It won't look statically rendered in yarn depth right, but it would if we, if you added the footer to the package, we upgraded it in next and then I did the thing that I did in the layout file and added it here then ran yarn generate it would become statically rendered. You can opt out of this.

A

If you want to, uh there is a next component um next client side. I think it's client-side, rendering only they they've they've changed the name of this tag a handful of times it used to be at one point: no ssr yeah. It is now it used to be ssr.

A

It used to be client only so if you had a component that needed to be rendered in the client side like if it needed, like browser apis to work or if you know you were like dynamically loading stuff into the client, like whatever reason you could wrap components in client only, um but now they have no dash ssr, which is the thing to use yeah.

B

A

um Oh and here's an example, I think this is like an older example. You know, like let's say you had this comments thing. um There's like a loading indicator right they just all they do. Is they wrap it in client? Only and nux just knows hey don't! So.

A

If you wanted your footer to be a client-side component, I don't think it should be, but if there was a good reason for it, we could wrap it in client dash only or sorry we could wrap it in no dash ssr and then nux would skip generating it, but it wouldn't. It would leave what it needed to render it as a client-side component, yeah.

B

A

We should use it sparingly, there's not. I don't think we have a ton of use cases for things like that for this particular website. So if you see no dash ssr, you should you know, ask the question of like why. Why does this need to be a client-side component, um because every time we do that, we, you know lose.

B

Yeah exactly yeah yeah.

A

For probably no something that we can do a different way.

B

Yeah for sure no that makes sense.

A

Cool can I answer your question on the footer.

B

Yeah yeah yeah excellent.

A

um Okay, other things, so I've talked about what it is. We've talked about, documentation, we've talked about sort of the slippers integration and what's happening there. uh We've talked about sort of the build steps. You know the difference between development and generating uh production does what yarn generate does, but it's got a different like environment variable, so we can switch on behavior in in production and in development modes. If we want right now, there's nothing happening there other than it's just a different environment.

A

Variable um nux might have some performance optimizations under the hood, but we don't need to worry about that. um What else do you have other specific questions? I.

B

Had one for the gitlab ci, that was just like generally just.

A

B

I guess I'm just looking at it because it's just like I haven't seen it so I'm curious like like. Is there anything particularly insightful about what you've done so far, or is it just a straight like.

A

um Yeah uh there is um so the first is uh thanks again to chad, wooley, um we started from a lot of boilerplate that he had put together for static site, gitlab, ci templates. um So a lot of these things you see here, especially with these. These comments- are performance and reliability. Optimizations right that we can do since we're mostly doing static site generation.

A

I had to deviate a little bit from what he normally had, because so we use so each job in the pipeline spins up a docker instance and grabs a docker image, um something that's different about this website than what we have in the middleman site in the middleman site. We maintain and publish a custom docker image for about doculab.com, uh so you may be used to working with tools that don't come with a lot of these images, um and I ran into this. I was like, oh, why don't?

A

I have this tool and I have that tool. I was like right because I haven't like written a custom docker for it. um I for a moment I was like okay, let's use the middleman one, but it comes with a bunch of stuff. We don't need like ruby, like we don't need any ruby here.

A

um So I was like no there's got to be a different way, so we default to generally speaking, most jobs will run with the node alpine linux image, which is just like a very slim version of a docker container that has like node js at version 15.4, and it's like pretty fast to spin up and tear down in other cases.

A

uh So I had to split out um a build step which uses node to build, so it says like okay, I have node, so I can run next because it's all node generated it's all node code, um but we have a deployment stage so build stage just uses default image, but our deployment stage needs um google cloud sdk, and the great thing here is that google cloud publishes an sdk image, but I needed to split out the build and deployment steps, so the deployment step only does things using the google cloud.

A

Sdk image and the build step only does things that it requires node, for so it's a little bit different than what we're used to working with, which is basically, we have like a custom in in middlemen. We have a custom image, that's kind of like can do whatever it needs to do, because over time it is sort of like people have built up what we needed um we're starting from a blank slate here. So there's nothing that custom works for us out of the box.

A

Eventually, we'll probably want to maintain our own docker image, that's specific, but in this case, at the stage we're in you know it's a very bare bones uh configuration, so um I just wanted to use whatever's out of the box and that's the same kind of deal with like the next configuration is like my guy.

A

My guiding um you know principle here is: do everything as standard as pot like if there's something that is like documented elsewhere, by a tool like go with the conventional documentation unless there's a really good reason not to, and because we can accomplish these tasks using like very conventional configuration items. I did that to start and we may find that eventually we need our own custom docker um instead, like our own uh docker image built, but we don't right now, yeah so.

B

A

Reason to make it.

B

Yeah, so I I would I would assert, is my own opinion like I would even challenge like do we need? uh Would we ever need a custom doc, like maybe maybe there's a good reason at some point, but like yeah, we.

A

Might be able to optimize, we might be able to, because there's some caching we can do if we use just one we might have. We might have a complicated job that needs like a bunch of different functionality and instead of like giving it like, because with docker you can say like we can just give it a whole like linux machine to do.

B

Right but like.

A

We don't need to like we like the the thing about docker. Is you can get all of your? You know environmental dependencies in one place and you can define them ahead of time, so you don't need to like.

A

So you can be like extremely consistent and performant, and so, if we had a job that needed like node and it needed ruby and it needed python and it needed google sdk and it needed like something else from our dns provider that we had to have a tool for like it might make a lot of sense to publish and maintain a custom docker image. um Just just like streamline everything and keep because, like basically like that to me, is the instance in which we would want to.

A

You start talking about complexity and like if we're at a point where we have all those things going on at one job, and we can't separate it out and there's just no getting around it.

B

Job is complex.

A

Right and so we should move the complexity into one place and we should say: hey: look. We can't get around this complexity, but what we can do is we can like say very clearly all of the complexity lives in our docker image and that's where we manage all the weirdness, and so, if you think, something's.

B

A

Right but we're not there yet, so you know there's no there's no complexity to manage here yet so there's no reason to manage it. Complexly yeah.

B

Gotcha, sweet all right, that's all! I really. I think.

A

Yeah awesome we'll have more to talk about when we've got pages built, uh including deployment stuff. um I don't think it's it's not particularly relevant because I don't have deployments running um right now, so I don't want to go into them because I don't even know one. I know 90 of how it's gonna work, but I won't know it until it's done so.

B

Something something I will probably want to do is switch our footer for the sop footer in about so that, like those because there's like slight deviations between the two and I think it would just look for a consistency like consistency like css experience like yes, I feel like it would just make sense to just have it all in one place. Yeah.

A

We're gonna run into this, and this is just something I think we're gonna have to handle on a case-by-case basis, like keep in mind, like the goal of this website, is to be the core marketing site and to reduce, like and and to very, like fine-tune the scope of what our team is responsible for, and so there will be points where we have inconsistencies and we're just going to have to either live with them or find out whether or not they're high enough.

B

Yeah but that's.

A

Something that that's a just do right, because that's that's, I think such a straightforward solve that. We don't need to like put together a complex decision and say, like oh.

B

Like do we need.

A

To like do this, it's like yeah, like I.

B

Mean like drop it right. This is cool this. This kind of seems like a thing where it's like I'll make an mr yeah and like like people, if, if we don't move forward with them, vmr that's a whole. Another story, yeah but like making. The mr is the first step.

A

Yeah, precisely and then we can talk about it in there about whether or not it makes sense to do my guess is it will make sense to do this. This is an easy example, but there will be harder examples where we find that certain types of pages aren't yet handled by next and there's some inconsistencies between them or like child pages and stuff, and we just will have to make some harder conversa to have some more like more challenging conversations about.

A

What's the priority right and like what's the driver to do it and that's you know a bigger strategy decision, um but the nice thing is we, you know we have the tools to. We have the tools to resolve those, and uh you know the the doing of the work is not the challenge, which is, I think, the the big solve here.

A

It is the strategy of the work, which is the challenge and, like I think you know, as with many other things like that's one of those things where like if you're, if your hardest problems are in execution, then like something in your system, isn't working because, like execution in 2021, uh you know writing software, like should be, should feel pretty smooth like you know, like.

A

I think that that's that's pretty true for for most, for work of the nature of hours like the execution should feel you know like pretty pretty smooth, um but if your execution doesn't feel smooth, then it's like. Okay, we need to like so like something has broken our system, but if your strategy is the most challenging thing, I think it's a perfect place to be in because, like the real work and value of what we do is like.

B

A

It's the same thing as you know, you move your complexity to your docker image. So if you've moved the complex decisions to your strategic decision making process, that's awesome, that's exactly where you want to be. You want to have challenging conversations and strategy, and you want to have easy choices and execution, and if you're there, you can move really quickly right and you can move like with purpose and efficiently and and do a lot of cool stuff.

B

Yeah, I agree I agree wholeheartedly. Thank you so much for setting up this time. Yeah.

A

This was fun. um I will stop us here and I'll post this up later today,.

B

Sweet. Thank you tyler. Well,.

A

See you everyone, thanks for watching.