Building a Showcase site with Gridsome + Netlify
Although building a static website has its fair share of benefits, it has a large negative impact when it comes to creating and maintaining the site. This impact led many developers to leave the static building methodology and take up a dynamic approach. The dynamic approach is generally easier to develop and maintain thanks to pre-made generators and content management systems (CMS).
However, in recent years more and more static site generators have emerged that combine the advantages of traditional static websites with the convenience of development on par with dynamic ones.
In this article, we will cover the steps of how to build a simple showcase website using one such static site generator — Gridsome and deploy it almost immediately using Netlify. The website will solely display a list of books that will be fetched through their International Standard Book Number (ISBN) by using OpenLibrary’s API.
This article is written with the assumption that the reader has at least basic knowledge in Vue.js, if not we advise you to continue reading after you become familiar with it. Knowledge of GraphQL is also preferred but not required.
Why a static page?
While dynamic pages are easy to maintain and develop, the cost and time to set up and host might not be worth it if the content of the website is mostly static.
In contrast, static websites are much cheaper and simpler to develop and host, and with the help of the static site generators their development is made even faster.
The downside is that any changes to the content would require a developer to manually apply them, however, most of these cases can be overcome via API calls from the client side (This may impose some security threats).
Therefore the decision of whether a website should be made dynamic or static is case-specific and should be made only after carefully considering the pros and cons of both options.
Why Gridsome?
Not more than a week ago Gridsome 0.5 was released and it caught our attention due to the technologies it uses.
Gridsome is a Vue.js-powered, modern site generator for building the fastest possible websites for any Headless CMS, APIs or Markdown-files. Gridsome makes it easy and fun for developers to create fast, beautiful websites without needing to become a performance expert.
In short, Gridsome allows you to create beautiful websites using Vue.js with features such as hot-reloading for better and faster local development, file-based page routing, static files generation for easy deployment, etc.
Content can be fetched through some of its source plugins or some external APIs, and then, stored in a local database where it can be accessed through its GraphQL data layer.
Let’s get started!
The first thing we need to do is to install the Gridsome CLI tool. We can do that from the terminal by using Node or Yarn with the following command:
// If using yarn
yarn global add @gridsome/cli// If using npm
npm install --global @gridsome/cli
Then we create our new project by using the gridsome create <project-name>command. In this case, we’ll use the name book-showcase for our project.
gridsome create book-showcaseIf we enter inside the newly created folder, we can see that Gridsome has generated some sample pages — Home and About, as well as a default layout that surrounds their content in the layouts folder. If we run girdsome develop while inside the root of our project, we can see their content by accessing localhost:8080 .
Due to its hot reload feature if we change something in the generated page or layout files, the changes will immediately be shown on the screen.
Creating the showcase
Before creating the showcase, we probably want to change the name of our website, which is currently set to the default — Gridsome. We can do this by changing the siteName property in the gridsome.config.js file generated in the root of our project. Let’s name our site Book Showcase, and so our gridsome.config.js file should contain the following lines:
module.exports = {
siteName: 'Book Showcase',
plugins: []
}Even though we changed the name, the link on the layout is still displaying the old value. This is because the hot-reload feature does not react to changes in the config files in the root folder. Therefore we need to stop our previous gridsome develop command and re-run it again.
Next, let’s create a new page for the showcase. We could have altered the contents of the Home.vue page, but we decided to create a new page to show off Gridsome’s automatic file-based page route generation feature. Create a new file called Showcase.vue in the pages folder of our project. As soon as we create this file, we can see Gridsome’s hot-reload feature generating a new route in the routes.js file located in the src/.temp folder. Furthermore, there is also an error 404 route that Gridsome automatically creates for us.
Although we created the new page and can access it by visiting localhost:8080/showcase, there is no way for the user to know how to access it. For that reason, let’s add a link to the Showcase page in the layout after the About link. We can do this by modifying the contents of the Default.vue layout file.
As you can see we are using the globally available g-link component to easily make the link to the Showcase page.
g-linkuses Intersection Observer to prefetch linked pages when link is in view. This makes browsing around in Gridsome very fast because the clicked page is already downloaded.
Our webpage should now contain the link in the layout:
Fetching the data
To create our showcase, we first need some data. We will fetch a list of books through their International Standard Book Number (ISBN) by using OpenLibrary’s API. We have prepared a predetermined list of ISBNs for this example. Please feel free to use the same list for this tutorial.
In order to fetch the data and have it available for the whole website, we need to modify the gridsome.server.js file in our root folder. The data then will be generated and stored as static JSON at build time and can be fetched through GraphQL queries. As we will be using an external API, we will use the recommended axios package to fetch the data and, therefore, we need to install it:
npm install axios --saveAfter installing axios, modify the gridsome.server.js file to contain the following:
Shown above, there are several steps that Gridsome will perform before building our website.
First, we fetch the details of each book by calling the openlibraryAPI with the corresponding ISBN.
After we get all of the book details and store them in the books array, we use Gridsome’s Data Store API to create a new type in our GraphQL data layer by calling the store.addContentType() method.
GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn’t tied to any specific database or storage engine and is instead backed by your existing code and data.
In short, GraphQL allows you to define types, their fields and allows you to query or mutate those types’ fields. As seen in the code above, we are creating a type namedBookEntryand specifying the route that we’ll use in order to view the details of this data source. Afterward, we iterate the book list and add each book as a node (a new entry) of the newly created content type. Note that we could have added the route field to each individual node instead globally, but in that case, we would have to replace the :id parameter with each node’s id. By putting it in the addContentType method, we tell Gridsome to do that for us. We shall also see later when we create the details page for the books that Gridsome will automatically generate its route and connect it to this content type hence the need for this field.
As with gridsome.config.js, in order to apply the changes to the gridsome.server.js file, we need to re-run the gridsome develop command. Since we didn’t make any changes to the View, there’s no way for us to see the changes from there. Instead, Gridsome provides us with a GraphQL explorer (Playground) where we can get a list of all available collections as well as explore and test queries when in development mode. Access the Playground by going to localhost:8080/___explore.
The Playground is pretty simple. It is divided into two parts, the space for inputting queries and the result display. On the right edge of the screen, we also have two tabs called Docs and Schema. By opening the Docs tab, we can see a drawer open up, displaying all of our possible queries including the ones for our newly created content type, bookEntry and allBookEntry. As we can see from the picture below, it displays which parameters it gets, and what it can return.
To confirm that our data has been properly propagated, let’s query the whole list of books, displaying only their ids and titles. If you’re unfamiliar with the GraphQL queries, you can read about it here. In summary, to query something in GraphQL, you specify the operation (in this case query) followed by the type that you wish to query and the desired fields you want to get in the response. We can do that by inputting the following query on the left side of the screen:
From the picture above we can see that we are querying the allBookEntry type and request for the edges field. Because GraphQL focuses on getting only the data that you need, it requires you to specify the subfields as well. Therefore, we ask for the id and title fields that are contained in the node subfield of an edge. You can check which parameters you can fetch by reading the content of the allBookEntry query in the Docs tab.
After inputting the query and clicking the button in the middle, we should get the results on the right side as shown above. Take note that the allBookEntry query returns a collection of edges, each edge containing a node and its neighboring nodes. Gridsome automatically generates this query with some useful arguments for sorting, filtering, and pagination. For more details open the Docs tab in the Playground.
Creating the view
Now that our data has been loaded into our Data Layer we can finally go back to designing the view of our showcase. Open the Showcase.vue file and input the following code:
From the code, we can see that all we do is fetch the books, iterate through each book and display the information we want to present.
We fetch the books through the <page-query> block where we can execute GraphQL queries in the same manner as in the Playground. The query we are using now is similar to the one we used before, but it contains more fields that we want to fetch (see the Docs tab in the Playground for details).
Gridsome offers two blocks for fetching data from the Data Layer, <page-query> and <static-query>. The former saves the result in the $page variable and should be used in pages and templates. The latter saves the result in the $static variable and is advised to be used in components.
After we get the data, we iterate it with the v-for directive and display each book’s data in a block. We make the title of each book a link (using <g-link>) to the detail page of that book (we’ll explain laterwards why the link points to /showcase/:id).
In this tutorial, we won’t use any UI framework, instead, we added some CSS to make the results look a bit more pleasant to the eye. We also added the shortenText method to limit one of the fields’ content to a maximum of 300 characters. The page should look something like this:
Creating the Detail Page
Next step is to create the detail page for each book. Gridsome advises us to use templates for this purpose.
Templates are used for single post views to GraphQL collections. Add a .vue file with the same name as a GraphQL collection to
src/templatesto create a template.
Since our collection is called BookEntry, we need to create a BookEntry.vue file in our templates folder. After creating the file, its route will automatically be generated in routes.js. Notice that even though the file name is called BookEntry.vue the generated route is /showcase/:id. This is because we previously linked the BookEntry collection to this path and therefore Gridsome automatically connected them for us.
Add the following code to the page:
Similar to the Showcase page, we fetch the book data through the <page-query> block and display the data by accessing the content in the $page variable. The only difference here is that in order to fetch the corresponding BookEntry, we are using the $id route parameter that Gridsome populates for us automatically because of the route linking we did in the gridsome.server.js file. The page should look like this:
Deploying the website
We successfully made our static showcase and are ready to present it to the world. The only thing left to do is to build it using the gridsome build command after which all of the needed files will be stored in the dist folder, and we’ll be ready to deploy our website.
There are many hosting services that we can use to deploy our website, but for the purpose of this tutorial, we decided to use Netlify which offers a rather simple (and free) way of deploying your website by just dragging the dist folder and dropping it in the specified area on their page. To do this, you will have to log in first or create a Free Plan account if you don’t have one already.
After dropping the dist folder, your website will automatically be hosted under a pre-generated hostname, which you can change in the Site Settings menu. In our case, we decided to host it at https://static-book-showcase.netlify.com.
You can view the whole project on GitHub.
Conclusion
As we saw in this tutorial, creating a website with Gridsome feels like a breeze, and if you use a service like Netlify, you can have your site up and running in no time.
Gridsome is still in its stage of development with its developers but from what we tried when making this tutorial we can only look forward to all of the features that should be added till the 1.0 version is out.
If any of you find Gridsome as amazing as we did and would like to contribute to it, make sure to check out their website or Github repository.
