Creating a New Qwik App
All right then. So in this lesson, we're going to create a new Qwik application using Qwik City. So if you go to the Qwik website, the link to this is going to be down below, then go to docs and then go to getting started. Scroll down a little bit. This is how we can quickly boilerplate a new Qwik City application.
So you see this right here, you can use npm, pnpm, or yarn. I'm just going to grab this npm and in my terminal I've already navigated to where I want to create this project, but I'm going to paste this in and then press enter. And once you press enter it's going to boilerplate this project for us. It will ask us a few questions. So I'm going to press yes for this.
And then we need to come up with some kind of directory name for our project. So I'm going to call this mario-life. Call it whatever you want. Press enter. And then we want a basic app using Qwik City, so press enter again. Would you like to install npm dependencies? Yes, we would.
And then once we've done that, you can see right here it says cd into the new folder mario-life and then run npm start. So I'll cd into mario-hyphen-life first of all. I'm not going to run npm start just yet. I want to open this up in my text editor, VS Code. So I'm going to type code and then a full stop, press enter, and then this is our starter project.
Project Structure Overview
So now what I'd like to do is give you a quick tour of the code for this starter application before we delete a lot of it and start from scratch. So to begin with, we have the node_modules folder for all the project dependencies, pretty standard. Then we've got a public folder for any kind of static files that you want to serve, like images or fonts, and they're going to be served at the root of your application, so /whatever-the-file-name-is.
And then the src folder is where you're going to be working for about 95% of the time. This is where all of your Qwik components, routes, and styles are going to live. So you can see we've already got a few files and folders inside here. The root file is basically the root component for the application, and it's all set up and ready to go. So for now you don't really need to edit anything in here. It just sets up the root component and wraps everything inside the Qwik City provider component.
Qwik city is the meta framework, by the way, built on top of Qwik that gives us the ability to set up routes and whatnot. It's a bit like what Next.js is to React. So in this file, we're just wrapping everything with the Qwik City provider. And inside that we have a couple of import things. We have the head of the document which contains the RouterHead component. I'm going to show you that in a minute. And inside the body we have a component called the RouterOutlet which is where all of the route components are going to get rendered. For example, if we have a component for the about page, when we go to /about, the about page component gets rendered right here.
The Components Folder and RouterHead
So just to quickly show you this RouterHead component which gets rendered for every route or page that we go to, head to the components folder. This folder is for any reusable or drop-in components. And the way Qwik likes to do this is place components and styles for those components in their own folders. For example, the header component has its own folder, and inside that is the component itself and a style sheet for that component.
This header component is just for the navbar of the starter site, and we'll change this later on. But I wanted to show you the RouterHead component. So open up that file and you're going to see that this is where we basically output a load of stuff that goes into the head of the document, so title or link tags, meta tags, etc. And we're actually looping through some more of those down here. So a lot of this content is dynamic, and it's stuff that we can pass into the document head from each page component. I'm going to show you how that works later on, but just know that this component is for outputting all of the stuff you find in the document head for each page.
We've also got this icons folder, which has a component full of SVG icons that Qwik uses for the starter site, but I might delete that later because we don't need it.
Routes, Layouts, and Starting the Dev Server
So finally we've got the routes folder down here. And this is where all of the different page components that you make are going to go. Right now we've got an index component for the index page or the home page. And we've also got a flower folder with an index component inside it and that's for the flower page. We've also got a layout file as well right here.
So we're going to talk a little bit more about pages, routes, and layouts, and all that kind of stuff later and what all of this stuff means. But for now I just want to run the application and see what this looks like in a browser. And by the way, we have a global style sheet right here called global.css next to the root components. So any global styles are going to go inside there. Anyway, to preview the application, just open up a terminal and you want to make sure you're inside the project directory and then type npm start. This is going to spin up a dev server so we can preview it on localhost.
Exploring the Starter App and Resumability
So now in a browser we can see that starter site. And at the top, this is the header component where all of those links are. These are all external links by the way, and they go to the Quick docs, not to other pages in this site. And then this content down here, this is all the home page content from the index component inside the routes folder. And if we scroll right down to the bottom, there's going to be a button we can click and when we do that, it takes us to another route, /flower. And this shows the index component that was inside the flower folder, right? So you can see this flower animation thing right here which changes when you slide this value up and down, which is cool.
Now what I'm going to do is just refresh the page first of all. And then if you open up the dev tools and go to the elements tab, you're going to see all of the HTML code for this page. And if you scroll through this, you're going to see a bunch of extra information in the page that Qwik serialized into it on the server. You can see all of that as HTML attributes and as comments throughout the page. And if you scroll right down to near the bottom of the document, you should see a script tag which just contains a lot of serialized JSON data. And this data is the initial state of the application on this page, which is self-contained in the HTML document, right? So this is all serialized state and data that Qwik added to the HTML page on the server so that by the time it reaches the browser, there's no need for hydration because all that information is serialized into the HTML. This is what allows Qwik to know about all the initial component boundaries, state, event handlers, etc. and only JavaScript code that's needed at the time we view components is ever downloaded on demand.
Customizing Page Content and Metadata
Okay. So what I'm going to do is head to the home page, the index component right here, and I'm just going to get rid of a lot of this home page content because we don't need any of that. So grab all of this stuff inside the div, select it all, and we're just going to get rid of it all. Okay, and we can get rid of that Link import as well because we don't need that anymore. So inside this div right here, I'm just going to replace that with an H2 and we will say, "Okey dokey," as Mario would say. All right, so don't worry about all this stuff. We're going to talk about how to create components a little bit later on, but we're just replacing the template inside the component for now.
Also, notice this thing down here. We have this DocumentHead type right here which has been imported. It's a type and it's been imported from Qwik City. So we export a constant called head, which is of type DocumentHead, and that equals an object right here. So what this is doing is allowing us for this page, this home page, to specify a title, any kind of meta tags, and also if we want we could add some link tags. Right? So I could change the title right here to something like Mario Life, like so. And then for this down here, this meta tag, we could keep it as description but I could change this to, "A blog site about everything Mario," as in Super Mario. And also we could add some link tags. So we'd say links, then this would be an array, and inside the array each object would be a different link tag. We'd have a rel attribute and that would be for example a stylesheet and then we'd also have an href attribute and I'm going to make this up, it doesn't exist but we'll say some-stylesheet.com/styles.css. Doesn't exist, but what I want to show you is that this thing right here that we export, this head, is actually then injected into this RouterHead component that we saw earlier. So it takes all that information, all this stuff right here, the title, the meta tags, and the links. And it goes off here and it says, okay, well put the title here that we specified inside this title tag. And then for any meta properties we have right here, any objects inside this array, cycle through those and output those meta tags. So in our case just a one. Then also down here, any links as well. So we have this right here and also any style tags, right? So this is what the router head is doing for us. It works in conjunction with this thing right here, this head which is of type DocumentHead, and you can add that to any page that you want. So this is the home page right now.
Anyway, let's save this and preview in the browser.
Verifying Changes and On-Demand JavaScript
Alright then, so we can see the updated home page content. Awesome. And if we look inside the DevTools in the Elements tab, open up the head, and then scroll down a little bit, you can see we have this title right here that it's injected, Mario Life. We should also have a link tag right here, which we do, and the href is some-stylesheet.com/styles.css. We have this meta tag right here which is the description meta tag and it says, "A blog site about everything Mario." So those things have been injected.
Now what I'd like to show you is if we go to the Network tab over here... I'm just going to move this over here a little bit so we can see. Now, I've put in here veets just to filter out any kind of ViteJS because I don't want that to be included in this little test because it's not Qwik stuff. What I'm going to do is refresh the page and notice no JavaScript gets downloaded, okay? And that's because we don't need to hydrate in the browser. We're just resuming the application from when it was rendered on the server. Okay? So this is the whole kind of premise behind Qwik applications. If there was some kind of interactivity on this page, like a button that we could click and then that would do something, as soon as I clicked that button it would download the JavaScript that we need from the server. So it's kind of on-demand.
All right. So anyway, now we have this new Qwik application up and running. In the next lesson, what we're going to do is talk about page components and routing.
