Guided: SolidStart Foundations

Welcome to the lab Guided: SolidStart Foundations.

In this lab, you will complete the implementation of a SolidStart application that tracks the vacation days for the employees of a small company. This simple application consists of two views. The first view will display a list of each employee, some data about them, and the total number of vacation days they have reserved. This table will contain links to a detail page that will give more information about the selected employee and allow you to reserve new vacation days for them.

While a significant portion of the program is provided, it lacks many critical features that you will be guided through implementing. To complete the lab, you will need to do the following:

• Create API end points that grant the client access to employee vacation data that is stored on the server.
• Use the API end points to populate a store that will track changes made in the application.
• Complete the creation of the application's home page.
• Complete the detail page that will list a single employee's information and allow new vacation days to be reserved.

While you are working on the application, you can view your progress by using the Run button in the lower right-hand corner of the screen. This will start a development server that will run your program and automatically update when you make any changes. You can view the application by clicking on the following link: {{localhost:3000}}. You do not need to run the program to test your progress, but it can be helpful to use this feature to see how SolidStart is reacting to what you are doing.

Important Files

A SolidStart application contains a large number of files, but you normally only concern yourself with a few of them. You will spend most of you effort on the files in the src directory. This contains all of the source files that you will use to create the unique features of your program. Within the src directory, the routes directory is another critical location to be aware of. This is the directory that will contain the individual web pages and API end points that make up your program.

In this lab, there are several files that you will be working with:

• src/routes/api/vacations/index.ts: This file serves as an API end point for the URL path /api/vacations. It is responsible for returning all of the vacation data that is stored on the server to the client.
• src/routes/api/vacations/[id].ts: This file handles requests to the route /api/vacations/:id where :id is the ID for a specific employee record. It will return the requested record from the server to the client.
• src/store.ts: This file is responsible for the creation an population of the client-side store that will track changes to the the employee vacation records.
• src/routes/index.tsx: This file serves are the root page for the application. In this program, it will contain a table that summarizes the employees and their vacations.
• src/routes/vacations/[id].tsx: This page handles requests to the /vacations/:id path and will show an individual employee's information as well as allowing you to reserve a new vacation date for them.

Communicating data between the client and server is one of the most essential aspects of a modern web application. SolidStart uses API Routes to allow end points to be quickly defined for use by the client. These routes use a convention-based approach to determine how to map incoming HTTP requests to functions that will handle those requests.

Note: You will be using RESTful end points in this lab, but SolidStart's API routes can easily handle other client-server communication systems, such as GraphQL and RPC calls. The only difference lies in how you implement the functions.

In this step, you will be implementing two end points:

• /api/vacations will return all of the vacation data held by the system.
• /api/vacations/:id will return the vacation date for a single employee whose ID matches the :id parameter. SolidStart end points can handle two kinds of return values: JSON messages and HTTP responses. The simplest implementation for an end point is one that doesn't require any information from the requester (other than the URL path itself) and sends a JSON message in response. This is exactly the scenario you have for the /api/vacations/ end point you will implement in the next task. This end point needs to respond to HTTP requests with the GET method. In SolidStart, you handle that method by exporting a function with the same name (GET) from the module. In this lab, the data is stored in data.ts which has already been imported into the module. The second API end point that you need is on the path /api/vacations/:id and will return a single employee's record, if it is found. This end point has two possible results:
• If the :id parameter matches an existing record, then that record should be returned.
• If the :id parameter doesn't match an existing record, a 404 - Not Found response should be returned.

Note: The source code for this end point can be found at src/routes/api/vacations/[id].ts,

First, you will implement the use case where the :id does match an existing record. Notice that the GET function is accepting an APIEvent object as a parameter. This object contains several members that help to efficiently manage the request. One of these fields, params, is an object that contains all of the route's parameters. These parameters can be accessed by using their names as a key (e.g., params['id']).

Stores are used by SolidStart to allow you to efficiently manage complex state information in your programs. It is optimized to detect changes that occur at any level, allowing the application to react to those changes. Stores also offer several mechanisms to update their state to facilitate clear and expressive code. The initStore function, located in /src/store.ts, is used during application startup (see /src/App.tsx) to populate the store with vacation data from the server. > Note: If you want to view the endpoint, feel free to navigate to the following link: {{localhost:3000}}/api/vacations.

At this point, the application has all the data that it needs to power the overview and detail pages. You will start by finishing the overview page that is mapped to the root page of the application. The page's source code can be found at /src/routes/index.tsx. Since this is a reactive framework, you might expect that functionality to be necessary for the page to work. As you will see, you won't actually need any reactive elements at all. This is an important aspect of using SolidStart - you have a lot of power at your disposal, but it isn't always needed. Creating the simplest solution to the current problem is often the most effective. This application does not use a single page application (SPA) architecture. Instead, it uses separate pages to render the different views for the user. Creating an application using this multi-page approach can often result in simpler and more maintainable programs, but it is sometimes less performant than SPAs. > Note: To see the functionality added in this step, feel free to click on the following link: {{localhost:3000}}. You can click on an individual employee to see how they would be able to request time off.

The detail page for this program, located at /src/routes/vacations/[id].tsx, will be the most sophisticated one that you create. It has three primary challenges:

• It must determine which employee's data to display.
• It must render that data.
• It must allow new vacation to be added to the current employee's reservations.

This page will use multiple reactive elements to respond to changes in the program's state. Some of these changes will be triggered by user interactions, while others will occur in response to state changes, such as when the store initializes upon page load.

Congratulations on completing this lab!

Throughout this lab, you've had a chance to experiment with some of the key features that SolidStart offers including:

• A fine-grained reactive architecture
• Convention based routing for both user-interface and data URLs
• Complex state management via signals, stores, and other reactive primitives

Feel free to continue to experiment in the lab environment to discover more about SolidStart. Remember that the {{localhost:3000}} link can be used to view the application as it develops.

Links

• SolidStart documentation
• SolidJS core documentation