Planning A Build

Welcome to Syntax. Today, we're gonna be talking about what you should be thinking about when planning or starting a new build or a new project. The Syntax team is going to be developing the third version of the Syntax site really soon. It was designed by, a good friend of mine, designer Travis Nielsen.

And we have the site design. We're ready to go. So just yesterday, we sat down and came up with a big old list and a whole bunch of things about what we need to accomplish, like who's going to do what, how we're going to organize things, decisions we're going to make about this code Bos, and we're gonna be talking all about that in this episode.

It's kinda interesting one because when you have either a a new build or you have a major rewrite or redesign, there's some, like, decisions that need to be made. Right? And especially for, like, me, you, and CJ, there's a lot we use a lot of different tech. We try absolutely everything.

So it's it's kind of important to Scott sit down and say, alright.

What are we gonna use? What are we what are we sticking with? What are we changing? Scott asking those questions of, like, how do we tackle this? Otherwise, we're gonna be mashing all kinds of different approaches and styles and whatnot together, and it doesn't doesn't become a good thing. So I I think this is a pretty common thing that hits teams that need to to to do a redesign, so I thought it'd be a cool episode. Yeah. Totally. And one of those decisions we made, obviously, Wes, is to use Sentry because the one, we already have it in the code base, so we're not gonna get rid of it now. But two,

last time when we launched the v two version of Syntax, Century was, like, pretty instrumental in making sure that after we launched, that this thing was actually as good as it felt on our machines because we got fast Internet. We got big pipes. And because of that, everything seems super good on our own local machines, but you don't know how other people are experiencing the website. They're experiencing when they click on something. What happens? How slow is it? How fast is it? All that stuff. And with Sentry, you can determine not only if your website's actually up. Maybe we wrote some code that crashed it and it went down or, it's it's having a hard time for some people, but we can also even get how fast it is for the users, which pages are slow, which database queries are bad, where the errors are, all of these things that are instrumental in making sure that you ship something good. So if you wanna ship something good, like we're about to, we're about to ship something good at a number of century.i0 forward slash syntax. Use the coupon code tasty treat, all lowercase, all one word, and get two months of century for free. So, Wes, let's talk about when we we got this design. We've been working on this design project. And in the past, the first Syntax site, you just went off and YOLO Node it in, like, twenty four hours. Yeah. The the second Syntax site, I put together a very structural design.

It was very here's the structure. It had no no seasoning. No no flavor.

And then you came in and were, like, tossing spices on and whatever, and it ended up, looking the way it looks now because of, the design flare you've added.

With this third design, you know, it's kind of a shift in in the way that syntax has grown, and it needed to have some new features and some new things that the current website, which JS, for all intents and purposes, a podcast's website.

We needed some some big rethinking of it. So that's why we need Travis. Architecture,

meaning that, like, we have many different kinds of content. Right? We wanna be able to do text content. We have video content and audio content.

And when you have so much stuff, how you experience it is is a whole another level of design. It's it's past just making it look good. It's how does somebody experience this? And and Travis did an awesome job. And now we're sitting here looking at these designs, and we're like, alright. Well, how do we now take our site, which we'll talk about what the tech stack is right in a second? How do we now move that into, this design without it being too much of a kludge and also too much of a, like, major major shift where it will never get finished. You know? Yeah. Totally.

And so, yeah, we we went outside help. We had all these meetings. We tweaked it. We did all this stuff. We worked with I worked with Travis before on the level up redesign. So levelup.video, I knew he'd do a great job. And, so because of that, after this project is done, we're we got the design comps. We're sitting down.

And I think, to me, the first thing that needs to be discussed is, like, project management organization even before you get into the code.

How are we keeping track of tasks and issues and those types of things? And so we ended up deciding on using the project features, the Kanban boards in GitHub specifically.

We're developers. All three of us working on it, we're on GitHub. We don't know any project managers or people who are non

developers going to be keeping track of tasks in this build? The day I use Jira to to build a website is is the day I'm I'm done web development. So I was happy that, like, we're not I don't I don't wanna spend a whole bunch of time just, like, managing the the management of this type of thing. I wanna be able to grab an issue, take a look at what's on, tear something off that's small enough, put the pull request in, move on to the next thing. Yeah. Totally.

Yeah.

So, because of that, the GitHub features feel really nice to use for that. We can keep track of everything there. So that's what we decided on. Again, that makes a lot of sense for for us.

Next, we wanted to talk about, like, the code base itself. The current site is built in SvelteKit. It's a big old site. There's a lot of stuff there. So what do we do? Do we keep that code base? Do we start over? Do we Mhmm. Put it in a put it in a folder and then bring in what we want? We decided that, ultimately, we didn't wanna lose our routing structure.

We didn't wanna lose our Git history on files. And so because of that, we're going to keep, like, pretty much most of the same code base, but we're gonna we're gonna start filleting and deboning the CSS out of that thing. We're essentially just ripping out the CSS and going to be keeping a large part of the general structure, a lot of queries, the the routing structure, those types of things.

It's it's always hard with with a code Bos like that because you don't Node, like, should I just totally start from scratch and start to port things in, or do I take what I have and Scott to just start tweaking it? And and we kinda decided sorta in the middle, which is just it it's gonna be probably, like, 70% of, like, a style redesign and a 30% of new features that that need to be added. But I I most of the existing features are not changing that much, So it makes sense in our case to simply rip out all of the CSS, but keep a lot of the functionality, like you said, where where all the routing, we have lots of, like, transcript work that that happens.

And and keeping all of that is is pretty important because, yeah, like you said, we don't wanna lose all of our Git history, especially with some of, like, the weird stuff.

It's like, why why is it done this way? We literally have a file called why do I need this dot m j s in the thing, and it's some weird hack to get Vercel to work with with a WASM.

And, if some if we were to, like, simply put in there, you wouldn't be able to go back and see, okay, what was what were the commits that led up to this,

hilarious file? Yeah. Which is it's so funny. So, we we ultimately just we want it to be a smooth experience. It's gonna be tough taking such a big code Bos and and getting it to be a totally new site, but I think there's enough there that Totally. Yeah. One thing that's important to say here when you're asking this is is simply just ask

open ended questions that maybe are are kinda stupid. So, like like, one thing I ask is, like, do we wanna stay with Svelte? And the answer to me is absolutely Wes. But I think it's worth asking those those those Wes. Even, like, we we're big on markdown. Right? The whole website is built in markdown, and we'll talk about that in a second. But I was like, do we do we wanna scrap markdown? Because there's some pains in that type of thing. So it's worth asking those open ended questions where you don't necessarily think you have an answer because we had some good conversations come out of those. Yeah. A lot of a lot of good conversations. And, honestly,

I I think meetings like this are so important.

And the more people are a part of your team, right, obviously, that that impacts how any of these things are gonna happen. But you do really need to know who are the decision makers.

In this case, it's the three of us. Right? We're not a big team. If you're a big team, chances are those decision makers are going to be a much smaller group, and maybe that smaller group can take feedback from a larger group.

But for us, we just don't have that that big kind of dynamic where we have to make sure that everybody's happy. So it was fairly easy for us to be like, do we wanna do this? Wes. No. Do we wanna do that? Yes. No. Whatever. But it's important to have these conversations and really lay it out. Like you mentioned before, if we just started working on it, there would be all kinds of things. I mean, we we got into, naming, how we're going to be naming things, even, like, CSS variable names, those types of things. And I guess maybe do we wanna take a minute to talk about the CSS itself? We're gonna be ripping it ripping it all out, one. Right? But we decided that, two, we're going to be writing most everything scoped to the component with a nice base of a global CSS utilizing just, you know, really good base CSS Bos off of CSS variables specifically.

And because of that, we Node to come up with variable naming patterns.

We Node to come up with ways to make tooling work. So there's Versus Node autocomplete for variables.

There's style ESLint to make sure that nobody's adding a color to the repo that doesn't exist as a variable, Wes.

And just, like, keeping everything in the same naming convention, the same style, everybody knows what's there, and every it's all going to be documented.

I I think also part of that conversation was let's let's have patterns and let's do things that Yarn, like, conventions, but, like, let's not go overboard to a point where it's exhausting to add something. The reason why there's hex codes in the code Bos for me is because it was too much of a pain in the ass to figure out what the thing was. And and sometimes you build so much of a framework. I'm not saying we did this, but sometimes frameworks are such a, like, a a hurdle that it's it's annoying to actually build something. So we we had this conversation around a lot of things of, like, are we going to build a whole system around something, or is that kind of unnecessary for it? And we sort of landed on, like, let's just have variables for the colors that we're going to use. Don't use the color straight up and or let's let's start with these paddings.

And if we find that we need something, then we'll have to to start to we'll have a discussion about, hey. Can we add a a weird padding? Even, like, on the Syntax website is I found that the the, like, border colors, there was not one that was faint enough for me. Right? And I I went and added one that was, like, kinda in between, in between those values rather than somebody just putting on opacity or just throwing in something that looks good for you. It's the, like, whole structure versus flexibility is just a constant battle. And we had Brad Frost on and talked about design systems as well where you want control, but you also want structure so that things don't, like, rot over time.

Yeah. No. I mean, I think that's really it because that is how rot happens. Right? And, luckily, there are tools out there, like we mentioned, like ESLint that can help you stay on track with those types of things. So I I guess speaking of that, let's talk about tooling. You know, tooling was a big part of this because with any JavaScript project, you have all them config files and all that stuff.

We wanted to get off of ESLint.

So we're gonna be trying Biome for this, which now has apparently pretty good experimental support for Svelte, which it didn't last time I checked on it. So we haven't Yeah. Tried it yet, but I'm I'm hopeful that it's going to work.

Yeah. I moved my personal website over from ESLint to Biome simply because my ESLint config is in ESLint eight, and then nine was released. But I'm using some plug ins with Airbnb, and, like, it it's so exhausting when things and, like, sometimes it doesn't work. You know? That's that's so exhausting. And I was like, I just let's try something else. You know? And I've been pretty happy with with Biome. It takes a little bit, to sort of tweak things, but Biome will be replacing both ESLint and Prettier for us, because it both does formatting and linting, and it's it's very fast as well. It's it's not fully featured just yet, but enough where I'm,

okay deploying it in my own code bases. Yeah. Yeah. Totally. And so Biome actually does have, like, linting for CSS stuff. You might be wondering, like, why use style int with that. Yeah. And when we looked at it, the rules and the amount of rules that exist for Biome just weren't weren't there for the types of stuff we needed, like establishing, like, a regex pattern for variable names, making sure that we are using variables for certain values, really sticking to this or that, which StyleLint does a very good job of. It's in in my opinion, it's really full featured in that regard. So, you know, it stinks to have to have more than one linter in the project, but, like Mhmm. You know, I guess you gotta do it sometimes.

Another big thing is we wanted it to be runtime agnostic. So we're trying to stick to both libraries and features that are not tied directly to any one JavaScript runtime.

That way, you know, if we we wanna run it on BUN, we can BUN it up. Wes wanna run it on Deno, we can, Deno to it. So Yeah. I think that was important for us. Yeah. It's

I'm very much about, like, future especially server JavaScript. Right? Future server JavaScript, if there is something that is not a Node API, but JS something that is a standard, like like, Wes streams is an example of one.

All of the winter CG APIs, all anytime that there is a standard API that works everywhere, ideally, some of these APIs are both browser and server, agnostic, which is really cool. So trying to stick to that as much as possible. Some of the APIs, like like the file system API, simply do not exist in a standard. And in some cases, like CloudFlare, the file system does not exist at all. So you you can't get totally there, but we're trying to to get as far as we possibly can. And that way, we'll be able to run it absolutely anywhere that we want it. Like, I would like to try to throw this on Cloudflare workers at some point to see what that looks like.

Yeah. Yeah. I know. Likewise. So, yeah, really giving that flexibility.

So, again, we've established a structure for our CSS. We've established a structure for our tooling, our overall communication process.

And, you know, another big one is development process itself.

We we've decided to do, you know, completely component based development in that we're looking at the components themselves specifically, but we're gonna be developing them more in isolation than we had in the past. I oftentimes am working by myself, and what I do is, like, you know, develop component based, flows, but do so usually in the layout. So this time, we're gonna be trying to do Node more in isolation.

We're gonna be using Storybook, which is not something I've I've really used a whole lot because it's always felt a little verbose for me. Yeah. But I do think it will be worth it. Yeah. I I think so as well, being able to develop them in isolation. And one thing we didn't even talk about was, like like, mobile or or responsiveness.

And I think we should probably try to go with container queries by default and then fall back to media queries. What do you think about that? Yeah.

I love that idea because, again, developing components in isolation, that makes so much more sense to me. And, like, container queries to me make overall more sense in terms of, like, how something responds.

So yes. Yeah. I I think so as well. Like, I'm trying to think of a situation where you would want a media query over a component query. And that might be, like, you know, like, some of the iPads or or sometimes when you're on your phone and you turn it, like like, sideways like this, you don't have enough vertical room to scroll. A lot of people forget about they think, like, media queries are all just about the width of the actual device. But a lot of times, people forget, like, no. If you're if somebody has their phone in landscape view and they're holding it, you you don't have a lot of vertical room. And if you're slapping, like, a sticky header and a sticky, like, media player, we'll probably only have, like, 40 pixels to actually show the content. So maybe that's one one time you want a media query, but I'm I I don't have a whole lot of other use cases.

Do you? I

I guess the whole time you've been But The whole time you've been talking, I've been really struggling to think of a time. But, you know, it's one of those things that, like, you sit here right now talking about it and like, is there any chance or blah blah blah? And then the moment that you hit that use case, you'll know it. But Yeah. Just thinking about it theoretically, I'm like, I don't Node. I don't know, man. I feel like container queries, like, what is the browser if not a container of itself? You know? The browser itself is a container. So deep.

Yes.

Wow. Yep. Oh, that's good. Oh, also, one other thing we talked about with tooling is, having the Versus Node extension saved into the repo itself.

I've been doing this a lot lately. When I install a new extension in Versus Code, I especially with things like linting. Like, I had my ESLint and prettier stuff set up the the plugins in Versus Code, like, set up globally.

And that was a bad idea because then I would have to disable them for every project where I was not using them. So I find that putting the extensions that are recommended and and active in the dot v s code folder, is a is a good idea. And then anyone who also clones the repo will have a suggestion. Oh, you should install these sick extensions for this workspace.

Yeah. Yeah. Totally. I love that. And I think that is something that I we we've done a poor job of in the past. And I say this as somebody I've primarily been a solo dev on so many projects. So it's like Yeah. The moment that it's like, what would be really helpful for everybody to get onboarded smoothly and have the same experience develop? It's just not a, a, like, a a way that I I have thought too much in my career, and I Node to change that with this site build. One other thing we didn't talk about is,

maybe throwing it in a dev container.

I've long not been a Docker or container enjoyer, but CJ is is huge on it. So maybe especially, you gotta have the database sort of come along with it. Maybe it's a a good use case for a a Versus Node dev container. In this case I I want it to be as easy as possible. I just wanna push a button, and the thing freaking works. I don't wanna have to, like, have a thousand steps to install it and have the right versions of everything.

That's always a big pain.

It's a big pain. Yeah. I agree. So I we'll be talking quite a bit about this build as we go. Mhmm. And then once it's done, we'll we'll do a deep dive into all of the decisions.

In fact, it might be really interesting to look back on this and say, how did that work out for us? Yeah. Yeah. Oh, you, decided to use this or do that, and it turns out x wasn't good enough or whatever.

Another thing I, you know, I I think is important in establishing these things in a modern context is, like, your AI rules files. Right? Because if you are like, I don't plan on using an agent to build most of the site or, like, even really any of the site. But, like, when you get the autocomplete and those types of things in your editor, it it is important to be able to make sure that the AI is on the same page for everybody.

Like, for instance, what are your specific code based rules? If I'm doing state in Svelte, it should be a class. It should look like this. It should be named like this.

Here are the document here's the Svelte docs. Here's this or that. Like, get our cursor rules or whatever it may be, your AI rules file in order, and everybody agree on the code styles. And then we are then, once again, unified on all that stuff.

Did we agree on on code styles as well? During our meeting? We No. We didn't. But we're all we're well, we're camel case. Right? Snake case? Snake case. No. We're snake case. Yeah. Yeah. We I wrote a whole bunch of the, like, transcript stuff in camel case, and I wish that I had the linter it was because the ESLint wasn't working at the time. Yeah. I kinda wish that it was because, now it's it's mixed. Right? It's not a big Deno, but We'll fix it. Right? Yeah. Yeah. Oh, yeah. It's it's probably not worth, like, fixing it until you touch that part of the code base again, but we're gonna be going with maybe we talk about the code styles. Right? So snake case for for all of your variables, like function declarations over, like, sticking them in a variable.

Our CSS variables are simply going to be what did we decide on? We warp saying, should we use, like like, color dash blue or simply just dash blue? C dash blue. Dash

blue. Just because for auto complete, you can then do hyphen hyphen c and get the auto complete of all of the different color options available.

So, otherwise, you wouldn't be able to have that. We all felt that color was too hefty for that, or at least that was what we we decided.

The word color, I mean. And I think we'll be doing that with, you know, whether it's padding or margin or those type of thing things as well. You know, you're developing a system. And I think that's the most important part JS everybody knows where to go to be on the same page in that system. But, yeah, coding styles, snake case, classes for state, which if you haven't you haven't used Svelte five very much, Wes, I know you've done a little bit right, you will like the classes for state bit.

I'll tell you that right now. It's it's it's very nice. The beautiful.

I'll say right now, we're gonna be using gray with an e, and I will be writing a linter rule. Any gray with an a will be, will fail the build, and, you will be paged

if it breaks the build. Okay. As long as we can spell,

color the right way Yeah. That's one thing I've never had a problem with being Canadian is switching between color with a u and color like, when you're writing in code. Like, I can I'll I'll even switch it in writing a comment. You know? Change the color to gray, and I'll have no problem writing with a u there. But when I'm writing in code, I'll I'll I'll do that, which is

is JS a skill of mine. Yeah. Well, that you gotta be, I guess. That has to be a skill of yours. It's, yeah, one of my few skills.

Content. Last thing I think we have here is is where will the content go? So right now, we have all of our content in markdown files, and we have a pretty good, like, system for that right now. The way that it works is you when we add a show, we write it in a markdown file. The build will pick up that it's a new file or if it's changed based on the hash of the file, and it will update that and put it into the database. And we did that because we wanted it to be % on GitHub. Right? Mhmm. But we really need it in the database. And and quite honestly, I just redid my website, and I have, I don't know, 700 markdown files as well or MDX files. And and I kinda regret it because it's it's such a pain in the butt. Yeah.

With it's it's getting way too big. Right? And I I was like, I kinda wish this was just a CMS.

You know? So we are going to be switching it from markdown files into, like, our whole own homegrown CMS, maybe.

Right? Like, we just we just wanna be able to edit a text area and and save it to the database. Well, I think the hard part is that, like, we are establishing a lot of sources of truth for data. So

So we have the markdown files, it which is syncing to a database. We have our podcast provider. We have YouTube. We have all these areas to update and whatever.

So we're like, well, let's just eliminate one of the big ones there, and let's just eliminate that component of it where, the markdown thing having to rebuild the site to add something to it. And we already built an admin section. I mean, it's not like a full featured CMS admin, but it is almost there. And so the amount of work it will take to get there isn't that bad. We already have a lot of the admin pages, the listing views, and stuff like that. It's just like building those forms and, building that that flow of making that an easy experience. So I think that part will be really nice to be able to manage the site in that way. I mean, that's how I always did level up, tutorials. So I'm I'm very used to I built my own admin section there, and it was, you know, very full featured. So, yeah, I'm a fan of that. I also think, like, a bit more UI

for editing the episodes. Like, right now, when we publish an an episode, we use, like, an, a Unix time stamp for the the published.

And in order to get that, you have to, like, go to the EPOC website and, like, copy paste it.

That probably should just be a date input. You know? Yeah. Yeah. Yes.

So I mean, that's what we did that's what we did in the ESLint production assistant app that CJ and I built. So just yeah.

Just bring it right into the right into the UI will be really nice. It has the downside of of people not being able to edit the notes,

which is a bit of a bummer. But Yeah. Third parties. If if we wanted to bring somebody on who wants to

be able to help us out there, there's always a possibility of opening up, like, limited role access stuff to modify certain things. Or like that. Like I just said Yeah. If someone wants to run the website, we can we can give, like, a seed database as well with a whole bunch of content in it, which we already have as Wes, but it'd be nice to even talked to, like, the folks at PlanetScale as well. I was like, would it would it be cool if someone forked the syntax repo and we just gave them a copy of the syntax database Oh, yeah. The, like, sensitive parts, like, the the pretty much just the users. Right? Yeah. That would be really cool.

Yeah. I think that's all we have here. Anything else to add?

No. I think the most important thing is that anything that you don't get communicated in these meetings and processes for your teams, those things will end up probably rotting at some point because people are just going to make their own decisions.

So if it feels really it feels intense to have to go through everything lined by how are we doing, see how Wes you know, if it feels intense to do it, just know that, like, having that establishment, in place before you even put pen to paper at all we'll give you a better outcome in the end a % of the time, especially with more people that are working on it. If somebody has to make a decision on their own on how to do something, then that means, like, you're gonna have five different ways that it's in, if if not more than that. So these types of meetings are really super important. If you're out there and you have these types of meetings with your team, big team, small team, whatever, how does this stuff typically go for you? Is there one person at the top saying Wes are using Pascal case on everything? Or or, like, is it more collaborative? And and how does that look? We wanna hear from you and what your teams are like because, obviously, we're a little three person team. A lot of us are used to working in a solo capacity.

So let's, let's let's hear how some some teams work on this stuff.

Sweet. Alright. Catch you later. Peace.