⚠️This article is a little heavier than some of the others. I found it best to try and explain the basic structure in a fair amount of detail, but feel free to skim to sections that catch your attention!⚠️

Getting started

So first things first, we need to actually install Gridsome. Like most modern JS frameworks, they have a nice CLI tool we can use to get the project quickly set up.

First install the Gridsome CLI,
npm i -g @gridsome/cli
yarn global add @gridsome/cli (gridsome recommends yarn)

Then all we have to do is create a new project straight from the CLI!

gridsome create ronini

cd ronini

Now we can start the servergridsome develop and navigate tolocalhost:8080 in your browser to view your site live. Pretty simple! 🥳

Directory Structure

Now lets take a look around and get ourselves familiar with what Gridsome has set us up with.

Now, I won't go overeverything because there is a lot going on here and Gridsome, like most tools in the Vue ecosystem, has pretty stellar docs, which you can findhere. I will go over some of the bigger talking points though.

Main.js

As you'll see with most of the files and folders in your newly bootstrapped project, the Gridsome team has done a great job of trying to outline the basics for everything. If you open upmain.js , you should see something similar to:

A few things to note here:

• We're importing and registering a component calledDefaultLayout globally. This is something called.. well.. alayout and we will talk about them very shortly.
• As the comments suggest, if we wanted to register components/filters/directives with the Vue instance, this is where we would do it. This is also where we would import a global css file, which we will also do in another article.
• You can see scripts mentioned as a potential import here. This is where you would inject things into the head of your document such as font awesome, google analytics, etc. (You might also be able to find a plugin for that - another topic we will discuss in a later article.)

/layouts

Let's go ahead and move into the layouts directory since we've already mentioned a layout component. Layouts are basically just large wrapper components that you can use to define thelayout of certain pages, routes, or even your whole site.

If you open up/layouts/Default.vue, and take a look at the code inside the<template> tags, you should see

So we have a few cool things happening here:

• You can see a component here,g-link, that is Gridsome's wrapper around Vue-Router'srouter-link. It really acts the same way, but with the added benefit of prefetching data from those links using intersection observers. What this means, is if the link is in view, Gridsome will make the request in the background and grab all that data for the user. This way, when the user clicks the link, the transition is almost instantaneous. This is how sites like Gridsome and Gatsby make the user experience feel so fast when they're navigating around the site.
• You'll probably also notice the$static.metadata.siteName, which is a topic for another time but the basics of it is this; Gridsome uses GraphQL under the hood to organize data. This allows you to write GraphQL queries in your components to fetch relevant data and present it like so. Here, we have fetched the name of our site from themetadata object. Pretty cool stuff! If you want to learn more about it, you can check the docshere.

• Lastly, we have aslot component. If you're unfamiliar with Vue slots, they are a way to create components that can be passed children. For example:
  

  // CoolTitleComponent.js<template><headerclass='awesomeHeader'><h1class='awesomeHeader--text'><slot></slot></h1></header></template>// Somewhere else in our app<CoolTitleComponent>  Wassssuppppp</CoolTitleComponent>

  In this example, we have a component calledCoolTitleComponent , which contains a component provided to us by Vue, calledslot. In this component we can do whatever we want, but for example sake let's just say our component applies some cool color to the text (purple, because it's the best) placed in ourh1 tag. Then somewhere else in our app we use our component and place the text "Wassssupppppp" in between the opening and closing tags, because why not.

  When Vue renders this component, theslot component will be replaced with the text that we passed in, and our component will be rendered as :
  

  <headerclass='awesomeHeader'><h1class='awesomeHeader--text'>        Wassssuppppp</h1></header>

  Slots are super powerful, and I would definitely recommend reading more about themhere.

  So for ourDefault component, this means that we can structure anything that is passed in the way we see fit! With the code provided to you by the CLI, you can wrap any component you make inside of theDefault component, and it will always render with a nav bar as seen in the code, as well as some global styles! We will be editing this file in our next article, so stay tuned 📺.

Index.html and App.vue (optional)

I'm going to group these two files together because they are both optional. Normally when creating a new Vue application you'd haveApp.vue as the root of all components, and the main entry point. Gridsome, by default, takes care of this under the hood. However, you can override the default file by creating one of your own if you just create anApp.vue file in the root of yoursrc directory. We will be doing this to apply global transition effects to our app later on.

Index.html is handled the same way by Gridsome, and can be overridden by creating anindex.html file in the root of yoursrc directory as well. This probably won't be used as often, as you can actually inject scripts and cdn links via themain.js file as we discussed earlier. However, if that can't be done, or you'd just rather not do it that way, you can override theindex.html and insert the content that way instead!

/static

This one is fairly straight forward. Any files and directories you place here will be copied straight to the/dist folder during build time. This is where you'd put something like a font file that you're serving yourself.

/pages

This directory is where you put all your, you guessed it,pages! Here you'll create.vue files that are various pages in your application. Any file you put here, Gridsome will automagically create a route for! So in the generated code we have:

├──pages/│├──Index.vue│└──About.vue

This means Gridsome has generated two routes for us,/ (index.vue, this is the root of the site), and/about. Now can navigate to these routes in your browser likelocalhost:8080/about.

So we can see how it works, lets go ahead and create a new file in our/pages directory calledBlog.vue. We'll put this into the file,

<template><Layout><div>        This is my blog!!</div></Layout></template><script>    export default{name:'Blog'}</script>

Save your changes, and navigate to[localhost:8080/blog](http://localhost:8000/blog) in your browser. You should see your page load!

/templates

Straight from the Gridsome docs:

Templates are used to create single pages for nodes in a collection. Nodes need a corresponding page in order to be presented on its own URL.

Now... some of you might have understood that. I wasn't one of those people - so let me try and explain in a way that I now understand.

If you are connecting your site to an external data source, say something like Contentful, Netlify CMS, or Wordpress, You would use templates to generate pages based on the data received from those data sources.

Still doesn't make sense? That's okay! Think of it like this:

Let's pretend you have a blog. The content of that blog is written using Netlify CMS and displayed on your Gridsome site. If the data of each of your posts (the headings, text, pictures, etc.) were all different flavors of Ben & Jerry's Ice Cream (Try Netflix and Chill'd, tweet @ me when you do 😋), then the container would be the template! The content might all change from from post to post, but they'll all have the same structure.

Okay.. but didn't you say this is whatLayouts are for..? - you, probably.

Yes.. and no. Layout dotheoretically do the same thing, but for different types of data. A layout is something you apply manually to your components, to structure any content inside. Atemplate isalso a way to structure content, but it is appliedautomatically to certain types of content. In this case, a blog post.

This does require some manual configuration which you can learn abouthere

This was part 2 in my series about rebuilding my personal site with Gridsome! I know this one wasn't quite as exciting, but next time we will go over plugins in Gridsome, and we will add my favorite CSS framework, Tailwind CSS! See you all next time, and be sure to follow me ontwitter!