NgSysV2-2.1: Installing Sveltekit and creating a simple all-HTML webapp

This post series is indexed at NgateSystems.com. You'll find a super-useful keyword search facility there too.

Last reviewed: Nov '24

1. Introduction

This post is designed to give you a first taste of the realities of life as a webapp developer. It concludes with a simple working webapp but must start with the tricky "installation" tasks you must negotiate to get to the point where you can run this.

While this is a nuisance, stick with it. Once you've got these out of the way, you'll have the chance to use Microsoft's VSCode editor to build a tiny piece of HTML. Finally, you'll use a VSCode terminal session to launch this in the browser via the Sveltekit local server.

Does this sound good? Then read on.

2. Installation

Absolute beginners might find this section a bit challenging, as it includes some procedures that aren't very user-friendly. However, it won't take long to get through, and you'll learn some basic skills that you will use frequently in the future. Here’s what you will do:

1. Create a Project
2. Install VSCode and open your Project within it
3. Open a terminal session
4. Install Node.js and npm
5. Install SvelteKit.

2.1 Creating a Project

Your first step is to use the Windows File Explorer tool to create a new project. You'll need to choose a name for this. I suggest you use lowercase letters and hyphens and keep the name short. Something like svelte-dev might be a good idea. You should also avoid locating your folder in Dropbox or OneDrive versioned storage. Webapp projects tend to become quite bulky and are liable to overwhelm general-purpose versioning systems. In any case, VSCode and Git will provide all the versioning you need.

2.2 Installing VSCode and adding your Project to its "workspace"

Follow the instructions at Getting Started with Visual Studio Code to install the software on your device. Launch it using its desktop icon and note the "File" entry in the menu bar at the top of VSCode's screen. Click this, select "Add Folder to Workspace", navigate to your project folder location and select/add it.

At this point, the VSCode screen will display three columns of information below its menu bar: a toolbar, an "explorer" panel showing "workspace" content details and a large blank area waiting for you to edit workspace files.

You may wonder why VSCode burdens you with a "workspace" concept when you only have a single project. This is because, over time, you'll accumulate numerous projects and find that you want to share code between them. The "workspace" allows you to operate on a group of projects. You can remove a project from the workspace by right-clicking on it and selecting "Remove Folder from Workspace". If you close and restart VSCode you'll find that it has remembered your previous workspace content setting and will reinstate it.

Since you will be using VSCode a lot you might consider "pinning" VSCode to your desktop toolbar. Note that, once you've added a project to a workspace, VSCode will hang on to it between restarts until you explicitly remove the folder with a r-click "remove folder from workspace" command.

2.3 Opening a terminal session in VSCode

You can open a new terminal session on your project by selecting "Terminal -> New Terminal" on the VSCode menu and then clicking your project's entry in the list that appears. If the "Terminal" option isn't visible on the menu bar, you'll find it in the "..." overspill area.

The "terminal" should appear as a sub-window at the bottom of the editing area on the right-hand side of the VSCode screen. Its height and width can be resized by clicking and dragging on the top and left borders. You'll find that you can also toggle it on or off using the ctrl' shortcut trick again. Currently, it is now waiting for you to enter "terminal session" commands on a line preceded by the full address of your project folder.

If your experience of IT to date has been entirely through the use of "click and point" on Windows (Microsoft) and iOS (Mac)screens, the heavy reliance in this post on the use of "terminal" sessions may come as an unwelcome shock.

The word "terminal" here takes you back to the early days of computing, long before the appearance of the "graphical user interfaces" that we use today. Developers then used "terminal" devices such as teletypes or "VDU" visual display units to issue operating system instructions by typing "commands" rather than by clicking buttons. These "command shell" interfaces still have great advantages for system programmers because they're easy to set up and are highly flexible. Terminal sessions thus continue to be widely used in the development process. Naturally, if you've been brought up on "point and click" interfaces, you will see them as a backward step. But you'll quickly find that they work well and will, in any case, add another useful building block to your growing range of development skills.

One could write a book about terminal commands but, for now, you only need to know a few basic facts. Firstly, you'll find that can't use the mouse to edit a terminal command. If you spot an error in the middle of a command, you must use the "Backspace" key to remove subsequent content and retype it. But this inconvenience is offset by the fact that the default Powershell terminal session used in VSCode keeps a history of the commands you use and allows you to reference a previous command by pressing the up-arrow key repeatedly until the one you want pops up. The down-arrow key reverses the process.

2.4 Installing Node.js and npm

You may already be feeling a little tired, but stick with it. You're nearly at a point where you can start using SvelteKit.

The "problem" is that SvelteKit is distributed over the Internet as a "package". Installation of the SvelteKit package requires a "package manager". What is a package and what is a package manager?

A "package" is a neatly bundled collection of code files carefully stamped with version numbers and accompanied by details of its dependencies on other packages. Modern software development practices use hierarchies of packages to share useful code components.

A "package manager" is a tool that enables you to "install" a package into a project by unpacking its code content and copying it into project folders. The package manager checks compatibility with any other packages that may have been installed.

The package manager you'll use here is called npm (Node Package Manager). Package management is demanding, so alternative managers are available to meet specialist situations. But the npm package manager is the standard choice and is recommended here. You'll use npm repeatedly during the development of a project as you find the need to include additional components.

Jumping ahead a little, once the npm package manager and its run-time environment have been installed, you can use it to install a "my-package" package into your project. You do this by launching a command like npm create my-packagein a VSCode terminal session. This downloads the "my-package" library files into your project's node-modules folder.

But there's a snag - npm requires a "Node.js runtime environment". So, this must also be installed.

The good news is that, for Windows users at least, Node.js is installed by downloading and opening a standard msi (Microsoft Installation) file. Even better, the installation procedure thus launched lets you install npm as well.

However, running the procedure is quite a challenge for a beginner. The basic download arrangement is documented at https://nodejs.org/en at Run JavaScript Everywhere but this is very light on operating instructions. You might find it helpful to check out the more detailed instructions at How to Install Node.js and NPM on Windows. Take your time with this. If things go wrong, all you have to do is uninstall Node.js and start again. The best advice I can give you is to use the standard default settings offered by the procedure - overrides are strictly for experts.

2.5 Installing SvelteKit

At last, you are in a position to make some progress! When you complete this stage, you'll be rewarded by a simple demo SvelteKit page running in your browser.

1. Open a terminal session in VSCode for your project, as before, and run the following npx command:

npx sv create 

*As an aside, npx is a "package runner" tool embedded within npm - it's installed automatically with npm

As of November 2024, this launches a SvelteKit dialogue to step you through a procedure to configure your project with Svelte 5.

As an aside, be assured that if things go wrong with this procedure and you want to start again, all you have to do is delete the entire content of your project folder and have another try. Note also that npm installations often display worrying lists of warning messages as they check for possible incompatibilities in the files they are building into your project. It's very unlikely that these will be relevant to you as a beginner so I suggest you simply ignore them.

Svelte's first question is "Where should we create your project?". Since your terminal session is already open in your project folder you can just press the return key here.

Now Svelte wants to know what style of project it should create. I'd like you to select "minimal" here. The procedure for doing this in a terminal session is slightly awkward because you can't use the mouse to toggle a checkbox as you would do on a web page. You indicate your preference here by using the down arrow key to position yourself on the "minimal" line and then pressing the return key

Now Svelte wants to know if you want to use TypeScript checking features. This advanced Javascript extension will be critical to you when you're working on a complex production-grade webapp (it polices your use of variable types in Javascript and ensures consistency). But you don't need this here and your learning curve is already becoming exponential, so I suggest you select "No" by pressing the down arrow twice and then pressing the return key.

Then, Svelte wonders if you'd like to include "additional options". The ESLint syntax-checking tool shown at the top of the list presented can be helpful. This can sometimes be a "noisy" nuisance, warning you about issues you're not especially interested in. But, on balance, I suggest you accept it here by pressing the space bar and the return key.

Finally, Svelte asks which package manager you want to use. Select npm

You can probably safely ignore any other options that might be presented.

Svelte is now all geared up to build your project. You give it the go-ahead, when requested, by entering the following command into your terminal session:

npm install

The curious display you now see played out on your screen may be your first sight of npm downloading package files into a project. You might find it instructive to note that the svelte-dev folder in your workspace window has suddenly blossomed with an impressive display of sub-folder content. This is the code that represents your "minimal" SvelteKit project.

It's not always the case that package software ends up in your project. Where you're installing a tool that might be useful shared with other projects, you can request that it be installed "globally". You do this by adding a "-g" "flag field" to your npm command. You'll see flag fields used widely in terminal commands. For now, though, leave your installer software to give you guidance on their use. Ask chatGPT to give you a tutorial on this sometime.

The Svelte installer now asks you to run npm run dev -- --open. Give it a try:

npm run dev -- --open

This launches the SvelteKit local server and runs your project within it. The local server has the job of creating "localhost" pages on port 5173 in your browser. If this sentence makes no sense to you, you will now see what it means anyway because the "-- --open" bit of the npm command automatically hands control to your browser and gives you a demonstration. Your screen should look something like the picture below:

This is a webapp coded with exactly the same sort of HTML that you saw in Post 1.1. The difference is that its content is being monitored by the SVelteKit framework. The code is currently sitting in your new VSCode svelte-dev project. Let's find the bit that displays the "Welcome to SvelteKit" banner on your browser screen, change it and see what happens.

Back in VSCode, with your project visible in its "workspace", use its folder/file hierarchy to navigate its content exactly as you would in Windows Explorer. You'll find that the project has acquired quite an impressive collection of code! For example, there's now a node_modules folder packed with tiny files. This is where all those files downloaded during your npm install work went. Now locate the +page.svelte file that you'll find in the src/routes folder and click it. (The significance of its name and location within the src folder will be clarified in future posts - let's simply say for now that the name "+page.svelte" is rather important). You'll now see the contents of +src/routes/+page.svelte displayed in the VSCode edit window on the RHS of the screen. The <h1>Welcome to SvelteKit</h1> line here should look familiar - yes this is the bit of HTML that displays the heading. Now change the line to read <h1>Hello there</h1> Save the file (using the usual ctrl S shortcut) and look at your browser again. Wow, the "Welcome to SvelteKit" message has been replaced by your "Hello there" message.

Because the SvelteKit server you started with npm run dev has been monitoring your project folder, whenever you change a file, the server automatically transmits the changes to the active application in the browser.

This is going to make development so much fun!

3. Summary

If you've survived this post give yourself a gold star. You've managed to get a SvelteKit webapp running in development mode and, just as importantly, have created the VSCode, npm and Node.js "scaffolding" that will get every future SvelteKit project off to a flying start.

The next post in this series will show you how to use Javascript and the Svelte "language" to add intelligence to your webapp.

Postscript 1: When things go wrong

It's not difficult to get in a mess with this stuff - the most experienced developers will sometimes mistype the name of an HTML tag and flood their screen with fearsome error messages. The difference is that they've seen it all before and know not to panic! As a beginner, when you see this sort of thing, you'll probably think you've completely wrecked your computer and must now buy a new one. Calm down. You can sort this.

Errors will be signalled in many different ways. Syntax errors in a .js (javascript) file open in VSCode will be flagged in the edit window. In the example below I've deliberately crippled the HTML code for the header message in a "minimal" project by dropping the closing > of the initial <h1> tag.

Note that:

• The erroring file and its parent folders have all been highlighted in red in the folder hierarchy. This means the code is broken and will throw an error message if you run it. Try this out - you'll find that the localhost page for your webapp will display a "500 Internal Error" when you refresh it. Back in your VSCode terminal window, a mass of error details will also have been generated by the SvelteKit server when you saved the errored file.
• The position of the "error" has been underlined in the edit window. When you mouse over this you will get a tooltip that gives you error details
• A "count" of the total number of errors and warnings in your svelte-dev project is displayed in the blue "status" bar at the bottom of the VSCode page.

This is a perfect example of why you need to stay cool. Behind all this mayhem lies a perfectly trivial error

In the first place, you'll see that this doesn't all add up. The system incorrectly highlights the concluding </h1> tag as the source of the error. The real problem lies in the broken opening <h1> tag. Once you've seen this a few times, you'll automatically think "Oh, there's something wrong with the tag pattern". Learn to hang loose. At least the system identified the correct line.

My general practice is that, when things go wrong with my code, I start by start fixing problems any highlighted by the editor. But there will be times when VSCode is perfectly happy but your browser is displaying an error. This is when you must look at the error messages displayed in your terminal session. These errors will be more serious and my advice is to take a deep breath, read the messages closely and try to think through what it is trying to tell you. If you're still stuck, paste the error message into chatGPT and ask for advice. Google searches citing Stackoverflow are also a good resource.

If you're still stuck, take a break, go for a walk and get some fresh air. That can make a huge difference. The great thing about computing is that, when things go wrong, there's always a reason. Even better, when you find that reason and fix it, it stays fixed. Consider yourself lucky - you could be trying to fix a problem involving people, where the exact reverse applies! Courage, mon brave. You'll find that coding problem and fix it, for sure.

Postscript 2: Working with VSCode

The VSCode Edit panel may feel a bit restricted when the VSCode is also displaying the Explorer panel. You might like to know that you can toggle the Explorer panel off and on by clicking the Explorer icon at the top left of the toolbar column.

Similarly, remember that when the Edit panel is overlayed by a terminal session, you can quickly toggle this off with the "ctrl ' " shortcut.

Finally, you will find it useful to know that multiple terminal windows can be active simultaneously. In this case, the menu bar of the terminal window displays a list of active terminals and enables you to switch between them by clicking on list entries. A "dustbin" icon here also lets you kill a window, though this may only be visible if you've made the terminal window big enough- space is always at a premium in VSCode.