DEV Community: MartinJ

NgSysV2-10.2: PowerShell Scripting essentials

MartinJ — Mon, 30 Mar 2026 17:18:08 +0000

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

Last reviewed: Apr'26

Introduction

The concept of "scripting" to automate PowerShell terminal sessions was introduced in Post 4.3 without any attempt to describe the script language's syntax.

This post still doesn't fully cover the subject, but here are the essentials, plus one or two "extras" I've found invaluable.

Variables, Arrays and Operators

A variable in PowerShell is a named container that holds a value, such as a string, number, array or object. PowerShell variables are dynamically typed, meaning you don't need to declare a variable's data type when assigning a value; it is determined by the assigned value. But note that once assigned, types are strongly enforced.

Variable names in PowerShell are introduced with a $ symbol. Variable names are not case sensitive, so, for instance, $MyVariable and $myvariable refer to the same variable.

Operators

Arithmetical — For mathematical calculations (+, -, *, /, %)
Comparative — For comparing values (-eq, -ne, -gt, -lt, -ge, -le)
Logical — For combining conditions (-and, -or, -not)

Comments

Introduce these with a # symbol,

Output

You can write to the console with the following arrangement

Write-Output "$MyMessage" # write this to the terminal

You can write to a file as follows:

$LogPath = "c:/path-to-my-log-file"
$MyMessage  = " .... "
Add-Content -Path $LogPath -Value $Message

Loops

For loop — Used when you know the exact number of iterations required. It’s commonly used for tasks such as incrementing counters or processing arrays.
While loop — Continues executing as long as a specified condition evaluates to True. It’s ideal for scenarios where the number of iterations depends on a dynamic condition.
ForEach loop — Designed for iterating through collections like arrays or output from commands.For example:

$i = 0 # Initialise a counter
while ($i -lt 5) {    
Write-Output "Iteration: $i"   
 $i++
}

Conditionals

Powershell's If-Else syntax follows the following model:

$num = 10
if ($num -gt 5) 
{    Write-Output "$num is greater than 5"} 
else 
{    Write-Output "$num is less than or equal to 5"}

"Null"

In PowerShell,

$MyVariable = $null

means “This variable exists, but it contains no value”

It is particularly useful because it evaluates to "false", along with :

$false → explicit boolean false
$0 → numeric zero
$"" → empty string
$@() → empty array

Which is very handy because you can now do:

$MyVariable = $null

if ($MyVariable) {
    Write-Output "True" # or - a handy shortcut - just say "True"
}
else {
    Write-Output "False"
}

Functions

PowerShell lets you define and reference shared blocks of code with the following model:

function Display-Greeting {
    param(
        [string]$Name,
        [int]$Count
    )
    Write-Output "Name: $Name"
    Write-Output "Count: $Count"

    for ($i = 1; $i -le $Count; $i++) {
        Write-Output "Hello $Name ($i)"
    }
}
...
Display-Greeting -Name "Martin" -Count 3

Options exist for the function to accept only valid parameter values - ask ChatGPT for details

Referencing a script with parameters

A parent script can call a subordinate "child" script as follows:

& ".\child.ps1" -Param1 value1 -Param2 value2

Meanwhile, the child script might be configured as follows:

param(
    [Parameter(Mandatory = $true)]
    [string]$Param1,

    [Parameter(Mandatory = $true)]
    [string]$Param2
)

The "Try ... Catch" block

Just as in JavaScript, you can capture exceptions and direct them to a "problem-resolution" block:

try {    
    # Code that might throw an error   
} catch {    
    Write-Output "An error occurred: $_"} 
finally {    
    Write-Output "This code always runs, regardless of errors"
}

More usefully, you might consider opening an account with pushover and configuring your script to send a notification to your mobile phone. Registration and configuration are extremely easy and, last time I checked, a lifetime account with pushovercosts just $5.

} catch {    
    curl.exe -s -o NUL --form-string "priority=1" `
        --form-string "token=aiu7yk ..obfuscated... 5uerqq6ix" `
        --form-string "user=ueczz ..obfuscated... jrv54u22" `
        --form-string "message=Something has gone wrong with your nightly .. run" `
        https://api.pushover.net/1/messages.json
}

The -s -o NUL parameter bit above simply suppresses the display of the "response" from curl.exe, which is no help at all when this is running in the Windows scheduler.

But when adding a try block, you need to know that PowerShell does not throw exceptions for many errors by default (especially for external commands). You can fix this either by adding explicit error-handling instructions to individual commands:

Some-Command -ErrorAction Stop

or, more realistically, by setting global instructions with:

$ErrorActionPreference = "Stop"

The "pipeline"

An advanced PS1 script will make extensive use of an arrangement that lets you "chain" commands together with a "pipe" symbol - | - that passes the output from one command as an object that then provides input to the next. So, in

Get-Process | Sort-Object CPU

Get-Process → produces "process objects"
Sort-Object → receives those objects and sorts them by a property

No string parsing, no fragile text handling — just structured data flowing through. PowerShell passes objects, not text, and binds them by property name or type. Here's another example:

Get-Service | Where-Object {$_.Status -eq 'Running'}

Get-Service → outputs service objects
Where-Object → filters them, selecting those with status "running"

Most pipelines follow this shape:

Producer | Filter | Transform | Output

For example:

Get-Process |
Where-Object {$_.CPU -gt 100} |
Select-Object Name, CPU |
Out-File processes.txt

You’ll use these constantly:

Where-Object → filter
Select-Object → pick properties
Sort-Object → sort
ForEach-Object → act on each item

NgSysV2-5.2: An Introduction to Git

MartinJ — Fri, 20 Feb 2026 10:34:46 +0000

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

Last reviewed: Feb'26

1. Introduction

In British slang, a Git is an abusive term for a sullen, contemptible person. As far as is known, Linus Torvalds never intended GIT to be an acronym, so one can only assume that the development of this world-leading version control software gave him a particularly rough time!

Words of abuse may pass your own lips from time to time, when you are using Git, but this is an invaluable tool, one now central to modern IT practice. Git is a version control system designed to manage the entire history of a software project. What kept Linus going? Let's find out.

When you're new to IT and are still busy creating your first VSCode project, the last thing on your mind will be turning that project into a Git repository (whatever that might be!). But with experience, you'll realise that managing source code is quite a challenge. You will make changes, find yourself in a mess and want everything to return to a stable state. Hmm. How are you going to arrange that?

Post 1.1 mentioned VSCode's "timeline" facility. This lets you view a time-stamped list of "saves" for a file and enables you to select any of them to replace the current version. This is fine in its own way, but has obvious limitations - for example, what if you wanted to reset a whole bunch of interrelated files to a particular point? Git, by contrast, is "timeline" on steroids (and then some!)

Git's "repository" mechanism wraps a project's files up in a framework that tracks changes between "commit" points. A "commit" lets you "sign off" on a collection of file changes as a "recovery" point for your project. Then, if things go badly wrong, you can use Git to roll back the entire project to whatever commit point you choose. Git helps you answer "how did this software change, when did it change, and why?" A "commit" is more than a simple file change; it is a recorded step in a project's evolution. Each commit represents a meaningful change, such as fixing a bug, adding a feature, or improving behaviour. Over time, commits provide a structured history of the software's development.

Git also provides a "push" feature that lets you create and maintain a copy of your local project on the web. With this in place, your carefully crafted project won't vanish into history when you leave your laptop on the bus! Typically, you would use this to create a secure backup "recovery" copy of your code when you deploy a new version of your webapp. In many workflow designs, a Git push triggers a deployment.

But in describing the "remote repository" concept in this way, I'm grossly understating its significance. In the world of systems engineering, the remote repository is the point through which large teams of developers, each operating on a local copy of the project code, coordinate their work. Git software provides the means of imposing order on what would otherwise be a nightmarish struggle. When Git is in control and the remote repository reflects the source of the production system, developers always know exactly what code is running and how it came into being.

A description of these "team" arrangements is well outside the scope of this post - the Pro Git book would be an excellent place to take you to a higher level. For now, here are detailed instructions for the things you are most likely to want to do as a beginner:

Turn the code for an existing local project into a repository and create a commit point
Recover to a commit point* Create a remote repo on the web and synchronise this with a local repo.
Create a remote Git repo on the web and synchronise this with your local repo.
Create "branches" on both your local and remote repositories to isolate your production code
Forward a "hot-fix" on "main" into "dev" using "git merge"
Create standardised Git workflows to safeguard your ongoing development cycle

2. Turning the code for an existing project into a local Git repository and creating a commit point

This is quite a complex procedure, but if you take it step by step and use ChatGPT to resolve any problems, you should be fine. Here we go:

First of all, you'll need to install Git software on your local machine. You'll find instructions for this at Git Downloads. The library code that this procedure installs on your machine lets you use both "raw" Git commands in terminal sessions and "packaged" Git tools in VSCode. In this post, I'll be using "raw" commands. Horrible as these are, I think they give you a better sense of what's going on than VSCode's built-in tool.
Now open a terminal session for your project and type the command:
```
git init
```
This will respond by telling you that an empty git repository has been established in your project. If you look at your project in Windows Explorer, you'll find that you can actually "see" the repository in your project folder - it takes the form of a .git folder in the project root. This folder contains all the information required to version-control the files in your project, together with a log that stores your commit history. If you ever get into a total mess with your Git install and feel you need to start over, all you need to do is delete this folder!
At this point, although you've got a repository, Git isn't actually doing anything useful. None of your files is currently "tracked" by the version control system - that is to say that Git doesn't know which files you want it to manage yet. To request that Git tracks all your files, you can use a git add . command. But first, note the following two warnings.

You need to think carefully before you ask Git to track all your files, because you are likely to eventually want to use a server-based remote to back up your local repository. It's important that this doesn't reveal security keys such as your Firebase Project and Service Account Keys. Google patrols GitHub (the website where remote repositories are held), looking for repositories (even private ones) that contain security keys. They will "cane" you if they find you own one. Ensure that any files containing such items are included in your project's .gitignore file. Also, when working in VSCode, it is recommended that you disable its Smart Commit feature. Use File > Preferences > Settings to search for Smart Commit and disable it if it is enabled. As mentioned earlier, VSCode provides powerful shortcut tools for managing Git repositories, but these can obscure your understanding of how basic Git commands work.

Warnings duly noted, submit your add command:
```
git add . 
```
Ignore any warnings about line-ending inconsistencies here. You can confidently leave VSCode and Git to sort this out between them. Your files are now tracked by Git.
Now create a commit point for your local repository with a second new Git command:
```
git commit -am "Your commit message"
```
Here, the "Your commit message" field is a unique tag that identifies the state of your repository at this point and enables you to restore it later, if required. Writing "commit messages" is an art form. You're forced by the system to keep the first line of the message short - 50 characters max. A typical commit statement would look like git commit -am "Stable login added". The "-a" flag here tells git to include all tracked files that have been modified or deleted, and the "m" flag tells it to label the commit with the supplied message. A useful command that gives you a simple list of all the commits you've made to your local repo is git log --oneline.

3. Recovering to a commit point

This is where things start to get useful. Try a little experiment. Make a few random changes to several files in your project and save them. Then, imagine you've changed your mind and want to revert your project to its initial state.

Type the following into your terminal session:
```
git restore .
```
Now, check your project. Yes, all the changes made since your last commit have been washed away - as before, the "." option has told Git to apply the command to all files. Wonderful!
The simple "restore" command introduced above restores your project to the most recent commit. How would you proceed if you wanted to restore an earlier commit? First, you need to find the "short hash" - the code that Git itself uses to identify commit points. There are several ways of doing this, but since you're using terminal sessions here, I recommend that you type in the following:
```
git log --pretty=format:"%h : %s"
```
The result will be a list of all your commits. Individual entries here will look like: c9f6037 : Stable login added. The c9f6037 bit here is the "short hash" for the full 40-character commit identifier. You can now restore all files and folders in your project to the "Stable login added" commit point with the following command:
```
git restore --source c9f6037 .
```
Other forms of the command are available to restore selected elements. Ask ChatGPT for guidance if you find you need it.

4. Creating a remote Git repo on the web and synchronising this with your local repo.

As suggested earlier, creating a remote repo on the web will provide a secure backup for your local work. This will involve some investment of your time, but I can guarantee that the time will come when you'll be glad you made it.

To get started, you first need to create a GitHub account. GitHub is a developer platform owned and operated by Microsoft. You can create a (free - thank you, Microsoft) account at Github Home Page, but I'm not going to describe this procedure here because it's a bit complicated and may change in future. Ask ChatGPT for advice if you get into trouble.
Once you're through this and logged into GitHub, click your profile icon, select "repositories/your repositories" (an empty list at present) and click the "New Repository" button. Give your repository a name - you'll probably want to choose something based on your VSCode project name - and tell GitHub whether it is to be public or private. If you select public, others can view it on the web and "clone" it (i.e., download it) as a local repository on their devices. You'll probably want to select "private" at this stage - you can always change your mind later. Decline creating .gitignore or readme files too - you'll complicate things enormously if you add anything to your new remote repo at this point. You can also safely ignore the offer to create a license. For now, simply click the green "Create repository" button at the bottom of the page. This will create a remote repository that is now waiting for you to populate it with a copy of your local project.
Back in VSCode, you now need to link your local repository to your new remote repository and "push" your local content into it. You do this with a series of Git commands submitted via a terminal session. To save your typing, GitHub will have provided the following default script for you to cut and paste:
```
git remote add origin https://github.com/mygitaccount/myreponame
git branch -M main
git push origin main
```
In this script:
- The "add origin" command links your local repo to the "remote" at "https://github.com/mygitaccount/myreponame".
- The "branch -M main" bit forcibly renames your local repo as "main". This post hasn't introduced you to the concept of "branches" yet, so just park this for the present. It will make sense shortly.
- The "push" command copies the content of your local repo to a GitHub version with a branch named "main".
You can confirm this by clicking "myreponame" on GitHub's "My Repositories" page and exploring its file hierarchy. You should find that the storage here mirrors your local repo.
With your remote repo in place as a remote copy of your project source, you can now experiment with the procedure for maintaining it. Repeat your previous exercise: make a few changes to some testbed project files and use VSCode to commit them, as described earlier, with a command such as git commit -am "New Changes added". Now push your local repo to its linked remote repository with the following command:
```
git push origin main
```
A visit to your repository's GitHub page should confirm that the changes have been received. Note that this is not just a copy of the latest state of your project's files - GitHub now contains the full history of your project. In a team development context, GitHub provides a shared space for developers to coordinate their work.

If you want, you can leave things here - you now have a secure backup copy of your project's code and a mechanism for maintaining it. But unless you're developing something purely to satisfy your own interests, there's a lot more to think about. In a high-stakes, commercial environment, the "pipeline" that deploys development work into production storage and thence to users' desktops is a complex, rigorously controlled procedure. Please read on to get some insight into the world of "Continuous Integration" (CI).

5. Creating "branches" on your local and remote repositories to separate your production code from development code

Suppose you've begun work on an enhancement to the current version of your system, and a crisis arises in the implemented version: a fault has been found, and a fix is urgently needed. What do you do? If you apply the fix to the code in your local repository, you may deploy untested development code along with the fix. Once you've experienced this situation, you will never want to find yourself there again! Let's stop it from happening.

The answer is obvious: create separate production and development environments within your local repository. Git "branches" were developed specifically to enable you to do this.

At the point when you last deployed your application, your local repository had only one branch - the "main" one you created at the outset. The following Git command creates a new branch called "dev" and switches you to it

git switch -c dev

You can always confirm which branch you're on by running git status.

You would create a new branch when you want to initiate a new line of development. Git enables you to do this without interfering with stable code. When the work is ready to be implemented, Git enables you to merge the changes safely into the main project history.

One important point to note is that when you created as above, this is not a copy of the "main" branch. Rather, it is a "peg" to which new versions of files representing a development track can be pinned

Also, naively, you might imagine that when working on your new "dev" branch, your view of files on "main" will be unchanged. This is not automatically the case. If you try changing "dev" branch files and switching back to their "main" versions, you'll find that the changes appear here too. How do you make branches work as expected?

First of all, you need to understand that file changes only get "pinned" to a branch when you "commit" them to it. You do this by making a commit on the branch:

git commit -m "Change test.txt on dev"

But if you do this right now, you'll find that you get a Changes not staged for commit error message followed by a list of the files that currently aren't "staged". So, what is staging?

Take a deep breath.

You need to be clear in your mind that, just as files are known to git only when you "track" them, files are included in a commit only when they are "staged". Even if your file was already tracked (because it was in your file hierarchy when you created your repository and ran git add .), you've now edited it, so a new version has been created. This is currently "dangling" loose. Git will only know which branch to pin it to when you "add" it to the staging area and commit to that branch.

When staging files, you could do them individually with git add myfile.text or, alternatively, do a preliminary git add . to add all current unstaged files. But most people will use the following command:

git commit -am "Change test.txt on dev"

This stages and commits all tracked and modified files in one go. However, if you had created some new files, you would need to get these tracked before committing, so it would be better to cover all bases with

git add .
git commit -am "Change test.txt on dev"

Try this out by switching to dev and changing the content of a test file. Now save the file and do a "git commit -am "Change test.txt on dev". When you switch back to main with a git switch main and re-open the test file, you should find that the changes are absent. Well done! You've now got the basic skills you need to create a robust production/development codebase control system.

Let's put this into practice. Assuming you have now acquired a Git account and successfully pushed your "main" local branch to a remote copy, here's how you would start from scratch to set up a clean dev branch mirroring your current main branch, and then give this its own remote copy.

First, clear the decks by making absolutely sure that "main" is clean and synced.

git switch main
git fetch origin
git status

You should see: "On branch main"

Since your current dev branch is only experimental, you should now reset it cleanly as an exact copy of your local "main" production branch

git branch -D dev # `-D` = force delete local branch only.
git switch -c dev # create fresh dev branch from main

At this point, dev is an exact copy of main. It's time now to complete the picture by giving the dev branch its own backup on the remote server. You do this with the following one-line command :

git push origin dev

You should see output like:

remote: 
remote: Create a pull request for 'dev' on GitHub by visiting:
remote:
To [remote repo address]
 " * [new branch]      dev -> dev
branch 'dev' set up to track 'origin/dev'"

This looks as if it's asking you to do something, but it's actually simply a combined conversation between Git on the server and git on the local repo that says, "Your remote repository did not previously have a dev branch. I have now created it". A visit to your remote repo should confirm this.

Perhaps you're surprised that you don't have to reference the url of the remote Git server when you launched the git push origin dev push command. This is because you're just creating a branch here, not a new remote. But it's a sophisticated command that does the following:

creates origin/dev
uploads history
links local dev to remote dev (otherwise kknow as "upstream tracking")

Once you've done this, you can backup your local dev branch whenevr you like by switching to it and issuing a simple git push.

6. Merging a branch - how to forward a "hot-fix" on "main" into "dev"

Once you've implemented a change to the production system you'll want to see this cleanly transmitted to the dev branch. You do this using the Git "Merge" command:

git switch dev   # Switch to the branch you want to merge INTO
git merge main   # Merge dev's changes INTO dev

This looks simple enough, but if you think hard about the complex conditions the process may encounter, your head will start to ache!

The best way of thinking about this is that merge "combines the independent changes both branches have made since they split".

This will be fine until it is found that the two branches changed the same thing in different ways. For example, one branch might have changed a file to say const x = 3; while the other changed it to const x = 4. In this situation, Git will report the problem as a "conflicted file", abandon the merge and leave you to sort things out.

A typical conflicted file error message will look like this:

CONFLICT (content): Merge conflict in temp.js
Automatic merge failed; fix conflicts and then commit the result.

It's easy to panic in this situation because it often occurs at points of maximum jeopardy in the development cycle. Also, Git does nothing to soften the blow - to quote an unknown developer, it "punishes you cryptically".

Here's what you should do in this situation:

Don’t panic (nothing is broken)
. Git has paused the merge intentionally.
. Your repo is safe.
Back in your VSCode editor, the lines in the temp.js file that are causing the problem will have been "marked up" with something like:
```
<<<<<<< HEAD
const x = 4;
=======
const x = 3;
>>>>>>> main (Incoming Change)
```

This is a "graphical" representation of the problem with the two sections of conflicted code laid out on either side of a "fence" represented by the "============" characters. On the "uphill" side of the fence, you have HEAD, the destination version of the code (dev), and on the "downhill" side (incoming change), you have the source (main)

What you need to decide is "what should this file say?” You need to design the final state, and the answer will usually be one of:
. keep one side of the fence only (and delete the other)
. or combine both
. or rewrite entirely

In practice, your files will contain a number of these markers and your task now is to edit your conflicted files until all the <<<<<<<, ======= and >>>>>>> markers have gone, leaving only lines that state precisely "what this file should do"

You're nearly there, but there's one final step you need to take before your git merge will work properly.

When a conflict occurs, Git no longer has a normal version of the file. Instead, it temporarily stores three versions of the file in the Git repo's index:

merge base (the file versions' common ancestor)
your "uphill" branch (dev/HEAD)
your "downhill" branch (main)

When you manually fix the file, you create a fourth version — the correct merged result. But Git does not assume you’re finished. You must explicitly confirm that the conflict has been resolved by "re-tracking" the file:

git add temp.js

You do this on the "uphill" "Head" branch (dev in this case) and follow it with a git commit -am "merge test complete" or similar. Git should now respond by telling you that the merge has been completed successfully

Addendum. The git merge command joins two branches in a way that preserves the history of commits on both partners. There is another form of join - the git rebase command that joins the partners in a way that pretends that all the commits on the "uphill" branch happened after the commits on the "downhill" branch. You would use this when you simply want to "tidy" your branch and aren't concerned about maintaining a rigorous commit history. This is for experts only and won't be discussed further here

7. Putting it all together - safeguarding your ongoing development cycle with Git

Life as a solo-developer situation usually consists of making frequent fixes and minor enhancements to the main production branch while more protracted work on a major extension continues on the dev branch. Each of these will ultimately lead to re-deployment of the application.

Here's the barebones of the two deployment procedures:

Minor enhancements to main

git switch main
# Move to the main branch (deployment branch)

git status
# Verify what will be committed; ensure no unexpected changes

git add .
# Stage all your changes (or specific files, if preferred)

git commit -m "Fix: "
# Create a permanent commit representing exactly what you will deploy

git push origin main
# Upload this commit to the remote repository
# Remote now becomes the source of truth for the deployment

# Run deployment script at this point - always runs on main

git switch dev   
# Now prepare to bring your dev branch up to date

git merge main   
# Merge main's changes into dev

git commit       
# Only if conflicts arise (a successful merge commits automatically )

git push origin dev 
# update dev's backup on the remote

Implementation of dev branch

git switch dev
git log dev..main --oneline
# check that main contains no commits that are absent from dev

git add .
git commit -m "Super new feature"
# Commit your new feature on dev

git push origin dev
# update the dev branch on the remote

git switch main
git merge dev
# bring main up to date with dev enhancement

git push origin main
# update main's backup on the remote

# Run deployment script at this point - always runs on main

If you ask nicely, ChatGPT will give you scripts to automate these processes.

8. Authentication issues and SSH

One of the most annoying issues you may encounter when using Git on Microsoft Windows to push local changes to the remote occurs when your terminal session cheerfully reports "Error: repository not found".

Of course, the repo may have been deleted, but this is unlikely. The message is usually just a smokescreen stating that VSCode has been unable to authenticate you with Git.

The most likely reason is that you have been working on multiple projects, each with its own Git repo and associated security keys. In this instance, the error message indicates that VSCode tried to push to your local repo with the wrong set of keys.

When you first pulled or pushed to your remote repo for a project, VSCode would have asked you to log in to that repo. At this point, it will have saved a copy of these in the Windows Credential Manager. This saves you the trouble of re-entering them the next time you want to access the repo. The problem is that, by default, the Credential Manager only holds a copy of the first entry you use. So, when you switch to another project, you're served incorrect credentials.

There are several ways to fix this. One is simply to open the credential manager and delete the Git entry you see there. When you try to push to the remote now, you'll be prompted to log in to Git, and an appropriate new entry will be created.

A better way is to clear out the Git entry, then prevent the problem from recurring by telling Windows to store permissions per repository. You do this by opening a terminal session on each of your projects and running the following command:

git config --local credential.helper manager-core

However, there's a more interesting way of resolving these problems. Here's the background:

For serious IT developments, the security of the codebase stored in a Git repo is a major concern. A huge amount of capital will be invested in its creation, and it is a juicy target for competitors keen to poach others' work. How safe are keys stored in Credential Manager, and how safe is the traffic passing from VSCode to Git when you sync an update or pull a new remote copy? If these thoughts concern you, you might find it useful to explore an alternative protocol called SSH (Secure Shell).

SSH was developed in 1995 by Tatu Ylönen. It's a cryptographic network protocol used to securely access and manage systems over the internet. It allows for secure remote login and command execution on another machine, as well as file transfers between systems. It works by establishing an encrypted communication channel that prevents third parties from eavesdropping or tampering with the communication.

For present purposes, because Git allows you to log in using SSH keys as well as the conventional HTTPS-based arrangement you've used so far, SSH provides an alternative to Windows Credential Manager for repo authentication. Suffice it to say that SSH's many security and practical advantages make it the standard security mechanism for Git operation by professional IT teams.

When you have a spare moment and would like to explore something new, interesting, and useful, I suggest you ask ChatGPT for an SSH tutorial. The technology has applications in many areas beyond Git, so time spent here will be time well invested.

NgSysV2-5.4: Browser Cookies

MartinJ — Tue, 03 Feb 2026 16:20:51 +0000

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

Last reviewed: February 2026

1. Introduction

Most times you open a new webapp, these days, you are greeted by an annoying pop-up that tells you "this site uses cookies" and asks what you want done with them. Here's an example

This is GDPR, the EU's "General Data Protection Regulation" in action. Although it is unlikely that more than one in a hundred of us have the faintest idea of why a cookie might be (or even care, particularly), you won't be permitted to enter the app until you submit to this interrogation.

This post attempts to clarify the situation by explaining:

what a browser cookie is
where you can see them
what their purpose is
why they may pose a danger to you
how GDPR and other standard bodies are working to minimise your risk
how you may assist their work by taking commonsense precautions

In the process, the post will also attempt to untangle the vicious knot of terminology that infests the subject:

first-party cookies
third-party cookies
third-party identity cookies

Sounds like fun? This post certainly lays bare some of the web's grubbier secrets

2. Cookie Basics - First-party Cookies

A cookie is a packet of information held in the user's browser storage. To view cookies for a website in a browser such as Google Chrome, right-click anywhere on the page, select Inspect to open Developer Tools, click the Application tab, and expand the Cookies section in the left sidebar. You'll now see a table listing the cookies associated with your website's domain. The graphic below shows the cookies that have been created by the "dev.to" website to help me write this post:

The most basic form of cookie provides a way of enabling persistent website behaviour between sessions - for example, you might use a cookie to let the user configure the language or the dark/light mode setting to be used on the website's pages. These are called first-party cookies because they are available only to pages on the website that set them.

Setting a basic (first-party) cookie:

Here's some JavaScript that you might use:

document.cookie = "lang=" + language

Suggestion: Why not try this now using the Inspector's console? Set a cookie with the value "eng", for example, check that you can see it in storage/cookies and then delete it with "right-click/delete".

This creates a cookie called lang with the value of the language variable. In passing, you might like to know that the document.cookie method also allows you to set attributes of the cookie, such as its lifetime and its scope (i.e., which pages can access it).

Retrieving a first-party cookie:

This is a bit harder because you have to find a named cookie in a browser's "cookie-jar" that contains cookies with many other names. The following would do the trick:

lang = document.cookie
  .split('; ')
  .find(row => row.startsWith('lang='))
  ?.split('=')[1];

When you run this, the lang cookie's value will be set on the language variable.

Here are some more examples of useful first-party cookies:

Session Management & Authentication: These are cookies that keep you signed in to websites, allowing you to move from page to page without re-entering your password.

Shopping Carts & E-commerce: These are cookies that store items in a shopping cart, allowing users to add products and continue shopping or return later to complete a purchase.

The important point to remember about first-party cookies is that information accumulated here is accessible only to the first-party app. This post now describes how other types of cookie can be used to pass information silently to other websites.

3. Third-party cookies

Here's a screenshot of the cookie storage from another site. It's the helpful word-finder webapp I use when desperate to complete a crossword.

Notice that the familiar first-party cookie entry for the crosswordsolver.org domain is now followed by a long list of cookie entries for other domains (eg visitor.omnitagis.com). Hmm - what are these doing there?

The word finder site is very useful to me, but it has never charged me for the service. How can this be? The truth is that behind the scenes, I'm paying for it in another way. This site has negotiated deals with advertisers who pay the site for advertising space. Fair enough, you might say, but there is more to this deal than meets the eye. If I click on an ad that has caught my eye, I will find that, behind the scenes, I have got more than I bargained for. The advertiser will have set a cookie in my browser storage that contains a unique code. Whenever I use crosswordsolver.org in the future, the advertiser will be informed. It doesn't know who I am, but it does know that the same person is making a return visit.

Even more sinisterly, if I click on other domains that carry ads for the same agency, the agency site will again be informed of my visit. This is because the cookie is shared. I am now being tracked cross-site.

Cookies like those owned by visitor.omnitagis.com in the Inspector's "cookies" view of the crosswordsolver.org site are "third-party" cookies. They appear here because the visitor.omnitagis.com site is embedded somewhere in the crosswordsolver.org site - probably as an advert. The information they supply is used to deliver personalised, targeted advertisements relevant to user interests. Suppliers are happy to pay considerable sums to agencies if they increase sales. I myself might be pleased to be alerted to products I might be interested in. But not always ....

The early history of third-party cookies

You might wonder why anybody ever thought that third-party cookies were a good idea. It seems, however, that browser designers thought third-party websites should be provided with a mechanism to configure persistent user state just like first-party sites. For example, a user of an embedded map should be able to set a region or location preference and see it restored after a session break. For simplicity, the designers opted to preserve this state in cookie storage and then sought ways to create and access third-party cookies.

Setting a third-party cookie

Third parties cannot use the document.cookie method to set a cookie for the very good reason that they are in a different domain. What they can do, however, is add a Set-Cookieheader to the response to a file request from the first-party site. Typically, this request would be received when the browser is loading the embedded third-party site.

To set a uid parameter in the third-party cookie, the third-party's server might use code like this:

res.setHeader(
  'Set-Cookie',
  'uid=ABC123; Path=/; SameSite=None; Secure'
);

res.sendFile('/path/to/file.html');

On successful receipt of file.html, the browser would detect the header and set the cookie as instructed.

Reading a third-party cookie

The "headers" trick is used again here. Obviously, the third-party can't directly address the first-party and ask for its cookie. In fact, it doesn't have to because the browser sends the third-party's cookie as a standard Cookie header with every file request to the third party's files.

The Get command launched by the browser would typically look like this:

GET /page HTTP/1.1
Host: tracker.example
Cookie: uid=ABC123; prefs=dark

How third-party cookies track user activities

In order to display an ad, a domain like https://www.crosswordsolver.org/ must launch a "Get" instruction to obtain files containing images, scripts, etc., from the advertising agent's website. As described above, if there is a cookie for this third-party website, the browser automatically adds it as a Cookie header to the Get request.

Initially, the browser won't have a cookie for this particular third party. Recognising this, the third-party server will duly create one by adding a set-cookie header to its response. The content of the cookie thus created will be innocuous - simply a unique identifier looking something like the uid=ABC123 example used above. But this is the point at which the third party has created the opportunity to track the user's subsequent activity - potentially indefinitely.

On every subsequent visit by the user to the website, the third party will be contacted again. This is because at least one of the files referenced by the ad will have been tagged with "no-cache," which requires a refresh. To minimise impact on site performance, this will be a tiny dummy file displaying a blank 1*1 pixel image or a minimal JS fetch. As before, the third-party cookie with its unique tag will be set, and the third party will know that "this user" has visited the site again. If the user actually clicks an ad, more information will be gathered, and the agency will begin to build a picture of the user's interests.

But worse still, as mentioned earlier, if the third-party domain has ads on other sites, the cookie created by your use of the first site will also take effect here. This is because cookies are stored in the browser's cookie storage solely by their third-party domain. The user is now said to be tracked "cross-site". It's important to recognise that, at this stage, the agency doesn't know who you are - it only knows that this is the same person it has seen previously. But as you'll see shortly, over time and through cross-matching with other information sources, identification may be possible.

This tracking will persist until you clear your browser's cookie history. As you'll know, this is a very disruptive action (deleting useful sign-in credentials, etc., along with any third-party cookies), so you won't be in a hurry to do it too often!

Finally, what a third party realistically infer from tracking data.

(a) You are the same user across many sites

If cookie ID=9f3a8c2e1b appears on, say, news-site.com, diy-forum.net, travel-deals.org, the tracker infers: “These visits came from the same browser/device, so they most likely reflect the interests of the same person.”

(b) These are your interests

From page context and ad clicks, trackers may infer:

Shopping intent (e.g. “barbecue equipment”, “insurance quotes”)
Hobbies (DIY, cycling, photography)
Travel plans (locations, timing)
Media preferences (politics, sport, finance)

This works even if you never click an ad.

From the originating site's IP address, Language and locale, repeated patterns, trackers might infer

Country
City or region
Sometimes workplace vs home patterns

(d) This is the sort of device you are using

From the request headers information, the tracker might be able to determine the type of device you are using, and whether this is one person or multiple people sharing the same device

(e) These are your behavioural patterns

Over time, trackers may infer: Daily routines, Active hours, Workdays vs weekends, Session length and frequency

This is often more identifying than name or email.

(f) This is the sort of person you are

Without knowing who you are, trackers can infer: Age bracket, Income range, Family status, Education level

(g) Potentially - this is who you are

On its own, the cookie is pseudonymous, but there is no guarantee that, given the opportunity to access publicly available information from other sites, a tracker could not make an informed guess about who you are.

In short, over time, a third party may build a cross-site profile of browsing behaviour and inferred interests, which may be commercially valuable for targeted advertising.

The sensitivity here is that the information is gathered covertly. The arrangement is now seen as abusive, and standards lobbies have united in their determination to see standards created that will put a stop to these practices

What has been done to curb the "threat" posed by tracker cookies?

Two points before answering this question:

Not all tracking is contentious. For example, tracking arrangements such as "Google Analytics" are invaluable in enabling sites to gain information about user behaviour - which pages are visited, how long they stay, and what buttons are clicked. This helps website owners explore performance issues and improve functionality.
Tracking monetises user activity, thereby funding many free services that one has become accustomed to taking for granted. Would it be a better world if one had to pay for every Google search or ChatGPT query in exchange for assurance that such use remained strictly private?

That said, you might like to know that among major browsers, Safari, Firefox and Brave now block third-party cookies by default. Chrome and Edge still permit them for now, but are actively phasing them out.

Also, where third-party cookies are still permitted, they must explicitly label themselves as such by setting the SameSite=None; Secure properties. This makes cross-site cookies more visible and auditable, both by browsers and regulators.

But even when third-party cookies are blocked, I regret to say that there are many other ways advanced technology can still track our activity online. Even without cookies, a server can correlate requests using:

IP address
timing
your browser's "signature"
request patterns

While these data are individually weak, collectively they are strong. The information they provide is probabilistic, but often good enough.

See the next section for some advice on common-sense precautions you might employ to limit your exposure

4. Third-party identity cookies

In an ordinary third-party cookie, the "payload" will contain only an anonymous (but unique) identifier. But if the cookie was created by a website that signed you in with an Identity Provider such as Google, there was previously an opportunity for the identity cookie to carry your email address.

Clearly, the information gathered by such a third-party identity cookie is enormously more valuable - and potentially enormously more dangerous to the individual that is being tracked.

Recent moves by apps to routinely use "federated sign-in" to authorise users would appear to magnify this risk enormously. The good news is that authentication gateways such as "Sign in with Google" operate under a new FedCM standard that is explicitly designed to prevent Google itself from setting a third-party identity cookie on the site.
See "Sign in with Google", "Google One Tap" and "FedCM" for further information

The bad news is that the app itself does know the user identity, and there is nothing, in principle, to stop them from selling this information to third-party advertisers on their site.

In principle, this is where GDPR comes in. GDPR is a legal framework that requires apps to disclose how they use your data. An app would experience a massive backlash if it were ever revealed to be systematically exploiting the trust that its users had placed in it

But in such a complex and obscure environment, it clearly pays to be cautious. Privacy-conscious users should ring-fence their activities and use different identifiers for different services.

5. Summary and practical takeaways

Browser cookies began life as a simple, pragmatic solution to a real problem: how to make a stateless web feel usable. Over time, however, the same mechanism was repurposed to support large-scale, cross-site tracking — often without users’ knowledge or meaningful consent.

Modern browsers and regulators have now recognised that this arrangement has gone too far. Measures such as SameSite restrictions, third-party cookie blocking, cookie partitioning, and FedCM are all attempts to restore a balance between functionality, privacy, and transparency. They do not eliminate tracking entirely, but they do make covert, ambient tracking much harder to justify and much easier to see.

For users, a few common-sense conclusions follow:

Not all cookies are bad — many are essential to how the web works.
First-party cookies generally pose limited risk when used responsibly.
Third-party cookies enable cross-site tracking and deserve greater scrutiny.
Consent prompts exist because the underlying practices were opaque, not because cookies themselves are inherently dangerous.
Blocking third-party cookies improves privacy, but it does not make tracking impossible.
Awareness — not paranoia — is the most effective defence.

For developers, the lesson is equally clear: privacy-respecting design is no longer optional, and mechanisms that rely on silent cross-site state are living on borrowed time.

The web is in the middle of a long, imperfect correction. Understanding how we got here is the first step toward using it more thoughtfully.

"Sign in with Google", "Google One Tap" and "FedCM"

MartinJ — Fri, 16 Jan 2026 19:15:17 +0000

Last reviewed: Jan '26

Introduction

You'll surely have noticed a growing trend toward apps signing users in with a "Sign In with Google" (or similar) identity provider (IdP) procedure.

This post:

Explains specifically how "Sign in with Google" works
Discusses why you might want to use it
Provides a Svelte/Firebase example
Describes the history of FedCM.

"Sign in with Google"

In the FedCM model, an IdP like Google lets you use a single account to sign in to multiple applications without creating new passwords.

Once "Sign in with Google" verifies that you are who you say you are (by virtue of your knowledge of an account's password and any associated 2FA credentials), it generates a cryptographically secure token for the app to pass to its secure backend processing. Here, the app extracts your account ID from the token and checks whether it is on its "whitelist" of permitted accounts.

The interaction is triggered by the display of a standard Sign in with Google button:

In a conventional sign-in, a webapp would use its own code to request and validate credentials. "Sign in with Google" enables you to replace this with Google library code. You also benefit from Google's secure cookies that allow Google to recognise returning users and issue fresh ID tokens. Your app can then sign in returning users with minimum fuss.

Here's an example of the dialogue (account id's have been blurred):

Here, you are explicitly told which app you're logging into and are assisted in selecting the Google account to use (you may have many - not necessarily all Gmail accounts). You are also given the opportunity to check which items (eg your name) may be supplied to the app from the information registered in your Google account.

Once signed in to a Google account, cookie caching can keep you signed in for a surprisingly long time. During this time, you may leave the browser, turn your computer off and back on again and still find yourself logged into the app.

But eventually, Google will decide that your "auth" is no longer valid and that it's time to re-authenticate.

Recognising that this creates significant "friction" for users, app developers can enable Google to let you sign back in with a One Tap prompt rather than the relatively cumbersome "Sign in with Google" procedure. The essence of this arrangement is that Google offers to skip the explicit account selection step of "Sign in with Google" by using the previously used account. The "One Tap" prompt appears as an ephemeral pop-up (formatted and displayed entirely by Google) that is floated alongside the conventional "Sign in with Google" button.

Here's a screenshot showing the interaction

As you can see, the ephemeral pop-up displays the account details for the targeted account (assuming it's still signed into Google) and invites you to re-enter the app by tapping the "Continue as ..." button. If you are unhappy that Google has selected the correct account, you can simply ignore the ephemeral and "Sign in with Google" instead.

As you may imagine, a good deal of Google magic is concealed within this procedure. All I'll say about it is that, in my experience, it seems to work well, but is difficult to test. This is because eligibility depends on prior user interaction, dismissal history, and browser heuristics that developers cannot directly control. More on this later.

Finally, I should say that in practice, you'll likely want to display your "Sign in with Google" button alongside those for other IdPs, such as Apple and Facebook. Here's an example of such an arrangement from the Binance site.

Note that this shows the use of "Continue with Google" as an alternative to "Sign in with Google" in the button text - see the sign-in-with-google code below for instructions on how to control both this and other characteristics of the button. Note also that the Binance login screen carries a button to register a Binance account for a user id. This is where Binance deploys the code to maintain its customer "whitelist".

Should you use "Sign in with Google"?

Here are some pros and cons:

(a) Reasons why you might be delighted to use a Federated Sign In

(1) It makes life easy for both users and developers

(2) A federated sign-in, such as "Sign in with Google", follows the FedCM (Federated Credential Management) standard. FedCM, ensure that the federated Identity Provider (Google, for example) cannot silently follow the user across apps. In this case, Google would only know that you signed in to an app, not how you used it or how that usage relates to activity elsewhere.

(b) Reasons why you might be reluctant

(1). For as long as I can recall, web users have been advised not to share passwords between apps. Now, IdPs like Google appear to be explicitly encouraging developers to write apps that authenticate using a common password.

For example, if your Google account is ever compromised, all associated "Sign in with Google" app activity is likewise at risk.

The first counter-argument is that security arrangements for IdP accounts are fearsome. I can guard my Google passwords with a variety of two-factor authentication methods, and Google will alert me to sign-ins from strange devices. It also provides recovery mechanisms to make it easy to reset a compromised password.

Developing a local sign-in to match such levels of sophistication would be quite a challenge.

The second counter-argument is that you don't *need * to pin all your app activity to a single IdP password because IdPs like Google let you create multiple accounts. You can still have a different account for each app if this is what you want.

Nevertheless, while Federated logins let you create a new account on the spot, it will clearly be a good idea to anticipate user pushback to federated sign-in by offering a wide range of IdP alternatives.

(2) Google's "One Tap" button means that a user may prolong the life of a sign-in indefinitely

The first counter-argument to this is that if you instinctively dislike this arrangement, it's not a requirement. The code examples below show you how to suppress "One Tap".

The second counter-argument is that if you want to withdraw a user's access to an app because, say, they have become "persona non grata", you retain the ultimate sanction of removing their Id from your app's whitelist.

Overall, the view seems to be that federated sign-in offers both a superior user experience and greater security. While I don't expect to see it used for the most critical applications, I'll certainly be using it in my own work. As a huge Google fan, my eyes light up when I visit a new app and see a "Sign in with Google" button.

My only caveat is that I would expect a mainstream app that uses FedCM sign-on for public access to also maintain a private, heavily restricted backdoor using conventional technology. Corporate employees operate in different circumstances and require exceptional control.

How to code for "Sign in with Google"?

For your project to use "Sign in with Google", it must first register with the Google Cloud console, obtain a Google API client ID, and provide various details about itself.

(1) Get a Google API client ID for your project

If you are using Firebase, you will already have registered your project in the Google Cloud console and received a Google Project ID. But now you need an additional Google API Client ID.

The procedure is straightforward and well documented by Google at Get your Google API client ID.

Once you've got your Client Id, add it to your project's .env file. The entry should look something like:

VITE_GOOGLE_CLIENT_ID=108 .. obfuscated ... m2gjhau.apps.googleusercontent.com

(2) Configure an OAuth Consent Screen

The Google document also describes the procedure for completing an OAuth Consent Screen, which "tells users the application requesting access to their data, what kind of data they are asked for and the terms that apply". Importantly, it also tells Google which 'authorised domains' it may accept, i.e. the web addresses in your app that are permitted access. For testing my webapp, I only needed http://localhost:5173 (though obviously, you'd add others for live purposes later)

(3) Build yourself a "sign-in-with-google" page.

This is a page that will:

load the "Sign in with Google" library
configure the Google Identity service
show the One Tap" ephemeral (if required)
render a standard "Sign in with Google" button

Here's the code that I've been using. Since I'm a Firebase developer working on the Svelte platform, this may not map exactly to your case, but I hope you'll still find it useful.

routes/sign-in-with-google/+page.svelte
<script>
  import { onMount } from "svelte";
  import { goto } from "$app/navigation";
  import { auth, signInWithGoogleIdToken } from "$lib/firebase.client.ts";

  let returnTo;

  // Load the Google Identity Services library
  function loadGoogleScript() {
    return new Promise((resolve) => {
      if (window.google?.accounts?.id) {
        resolve();
        return;
      }

      const script = document.createElement("script");
      script.src = "https://accounts.google.com/gsi/client";
      script.async = true;
      script.defer = true;
      script.onload = resolve;
      document.head.appendChild(script);
    });
  }

  // Create a callback function to return control when Google successfully
  // returns an ID token
  function handleCredentialResponse(response) {
    signInWithGoogleIdToken(response.credential)
      .then(() => goto("/" + returnTo))
      .catch((err) => console.error("Firebase sign-in failed", err));
  }

  onMount(async () => {
    // Parse the redirectTo parameter from the current URL
    const urlParams = new URLSearchParams(window.location.search);
    returnTo = urlParams.get("returnTo") || "/";

    // Load the GIS library i
    await loadGoogleScript();

    // Configures Google Identity Services (GIS). Nothing visible happens yet -
    // - you have just set the rules.
    google.accounts.id.initialize({
      client_id: import.meta.env.VITE_GOOGLE_CLIENT_ID,
      callback: handleCredentialResponse,
      auto_select: false,
      cancel_on_tap_outside: true,
    });
    // you have now:
    // 1. Identified your app
    // 2. Set a callback (handleCredentialResponse(credential)) that will fire
    //    when Google successfully authenticates the user.
    // 3. Told Google not to sign the user in if Google already knows who they are.
    //    (Important for avoiding “why did it log me in?” surprises.)
    // 4. Told Google that if the user clicks elsewhere, it should dismiss One Tap cleanly.

    // At this point:
    //    - No sign-in has happened
    //    - No UI has appeared
    //    - You’ve just set the rules

    // Tell Google to show the One Tap Sign-on if appropriate. Omit the following
    // statement if you don't want this
    google.accounts.id.prompt();

    // Specify the format of the "Sign in with Google" button
    google.accounts.id.renderButton(document.getElementById("googleBtn"), {
      theme: "outline",
      size: "large",
      text: "signin_with", // or "continue_with"
    });

    // Skip page if already signed in
    return auth.onAuthStateChanged((user) => {
      if (user) goto(returnTo);
    });
  });
  // This is completely independent of Google Identity Services. What happens here:
  //  1. Firebase checks its persisted session (IndexedDB)
  //  2. When resolved, it calls the callback once
  //  3. If user exists: the user is already authenticated you immediately redirect to /returnTo
  //  4. If user is null: stay on this page and let "One Tap" or "Sign In button do their work
  //
  // Key insight - you are coordinating three independent state machines:
  //  - Google Identity UI
  //  - Firebase authentication
  //  - SvelteKit navigation
  //
  // In summary: This code sets up Google sign-in UI, lets the user authenticate
  // if needed, and uses Firebase as the single source of truth to redirect authenticated
  // users without races, loops, or double sign-ins.
</script>

<div class="min-h-screen flex items-center justify-center bg-slate-50">
  <div
    class="bg-teal-200 border border-black rounded-xl
           px-[10vh] py-[10vh]
           max-w-md w-full
           flex justify-center"
  >
    <div class="rounded-md overflow-hidden">
      <div id="googleBtn"></div>
    </div>
  </div>
</div>

TLDR: Notes

The code above declares a function to load the Google Identity Services library. This is used to ensure the load completes successfully when the function is deployed later in the code. Google Docs say: "Be sure to load [the library] on any page that a user might sign in on". Naively, I thought this could be achieved by simply adding it to my project's app.html file. This didn't work at all! Svelte's complex hydration means you need to explicitly load it on your pages. The asynchronous code to load the library is called here with an await. It is defined as a function in case circumstances change, and I need to centralise it as a "helper"
Confusingly, while Google Docs talk about the "Google Identity Services library", the library is actually held in "https://accounts.google.com/gsi/client"; GSI ("Google Sign In") is the historical API surface

(4) Create a Svelte fedcm-test route that triggers a login and displays some test data.

The following +page.svelte testbed triggers a sign-in to get a Google ID and, if successful, passes this to a +server.svelte file that checks if the user's account contained in the Google ID is included in the app's "whitelist" of permitted users. If the user is accepted, this server then returns a list of dataEntry items from a Firestore test_fedcm_data collection and +page.svelte displays them.

routes/fedcm-test/+page.svelte
<script>
  import { onMount } from "svelte";
  import { auth } from "$lib/firebase.client.ts";

  let dataEntries = [];
  let error = null;
  let loading = true;

  onMount(async () => {
    try {
      const user = auth.currentUser;

      if (!user) {
        throw new Error("Not authenticated");
      }

      // pass the user's idToken (containing their email address
      // and other pieces of user information) to the secure 
      // server-based code in fedcm-test/+page.server 
      const idToken = await user.getIdToken();
      const res = await fetch("/fedcm-test", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${idToken}`,
        },
      });

      const data = await res.json();

      if (!res.ok) {
        throw new Error(data.error);
      }

      dataEntries = data.dataEntries;
    } catch (err) {
      error = err.message;
      dataEntries = [];
    } finally {
      loading = false;
    }
  });
</script>

<div class="min-h-screen flex items-center justify-center bg-slate-50">
  <div class="flex flex-col items-center">
    <!-- Teal panel -->
    <div
      class="
        bg-teal-200 border border-black text-black
        rounded-xl
        w-[75vw] h-[75vh]
        md:w-[50vw] md:h-[50vh]
        flex
      "
    >
      <div
        class="
          w-full h-full
          overflow-y-auto overflow-x-hidden
          overscroll-contain
          pl-[15%] pr-4 py-4
        "
      >
        {#if loading}
          <p>Loading…</p>
        {:else if error}
          <p class="text-red-600">{error}</p>
        {:else}
          <ul class="space-y-2">
            {#each dataEntries as dataEntry}
              <li>{dataEntry}</li>
            {/each}
          </ul>
        {/if}
      </div>
    </div>
  </div>
</div>

(5) Create a server to check that the user is permitted to use the webapp and to return data for display

Here, in Svelte, I use a +server.js file. This means that all the processing here occurs securely on a cloud host (as opposed to insecurely using JavaScript on a web client). Because I'm using Google's Firebase, this requires me to obtain a Google service account.

routes/fedcm-test/+server.js
import { json } from "@sveltejs/kit";
import admin from "firebase-admin";
import serviceAccount from '/secrets/service-account-file.json';

// Retrieves the Google Account Id for the logged in user and check whether
// this appears in the "test_fedcm_whitelist" table. If so, it returns the 
// contents of the test_fedcm_data table. 

if (!admin.apps.length) {
  // a firebase service account is required in order to authorise server-side 
  // firestore access. This is drawn from the project's "secrets" file
  admin.initializeApp({
    credential: admin.credential.cert(serviceAccount)
  });
}

const db = admin.firestore();

export async function POST({ request }) {
  try {
    const authHeader = request.headers.get("authorization");
    if (!authHeader?.startsWith("Bearer ")) {
      return json({ error: "Missing auth token" }, { status: 401 });
    }
    const idToken = authHeader.split("Bearer ")[1];
    const decoded = await admin.auth().verifyIdToken(idToken);

    // idToken has been encrypted by "Sign in with Google" using Google's 
    // private keys.  verifyIdToken() now validates it using Google's 
    // public keys and checks that it:
    //    . Was issued for your project (aud claim)
    //    . Comes from a trusted issuer (iss claim)
    //    . Hasn’t expired (exp claim)

    const userEmail = decoded.email;
    if (!userEmail) {
      return json({ error: "No email on auth token" }, { status: 403 });
    }

    // Check that the user's Google Account Id is included in the list 
    // of authorised users
    const fedcmWhitelistSnap = await db
      .collection("test_fedcm_whitelist")
      .where("whitelistEmail", "==", userEmail)
      .limit(1)
      .get();

    if (fedcmWhitelistSnap.empty) {
      return json({ error: "Access not allowed" }, { status: 403 });
    }

    // Fetch the list of fedcmData entries and return it as a JSON
    const fedcmDataSnap = await db
      .collection("test_fedcm_data")
      .orderBy("dataEntry")
      .get();
    const dataEntries = fedcmDataSnap.docs.map(d => d.data().dataEntry);

    return json({ dataEntries });

  } catch (err) {
    console.error(err);
    return json({ error: "Server error" }, { status: 500 });
  }
}

(6) Create some data in Firestore:

The code above assumes that you have also created two Firestore collections:

test_fedcm_whitelist containing a set of whitelistEmail id values for accounts you want to have access to the app
test_fedcm_data containing a set of dataEntry test items you want the app to display

(6) Create a listener to ensure that all pages for this app trigger a login request before proceeding

In Svelte, I do this by creating a +layout.svelte file. By placing this at the top of the fedcm-test folder tree, I ensure that login will be enforced in all subordinate routes:

fedcm-test/+layout.svelte
<script>
  import { onMount } from "svelte";
  import { auth } from "$lib/firebase.client.ts";
  import { goto } from "$app/navigation";
  import { page } from "$app/stores";

  let user = null;

  onMount(() => {
    // set a listener that will be called whenever a page loads. If 
    // the user hasn't got a Google Auth (possibly because this has 
    // expired), they are directed to sign-in-with-google
    return auth.onAuthStateChanged((u) => {
      user = u;
      if (!user) {
        const returnTo = encodeURIComponent(
          $page.url.pathname + $page.url.search,
        );
        goto(`/sign-in-with-google?returnTo=${returnTo}`);
      }
    });
  });
</script>

{#if user}
  <slot />
{/if}

(7) Test the code

When your app is running in a Svelte project's "dev" server, the browser should respond to a localhost:5173/fedcm-test URL by displaying a "Sign in with Google" button. Signing in here with a valid Google count that uses a Google account id that is included in the test_fedcm_whitelist collection should list the items included in the test_fcm_data collection.

If you rerun the localhost:5173/fedcm-test, you should find that "Sign in with Google" is skipped and the test_fedcm_data items are displayed directly - you are still signed into your Google account, and Google remembers its association with your app.

Google will break its association with the signed-in account if you wait long enough or use a "Sign out" button in your webapp. I haven't covered "Sign out" here, as this post is already way too long, but ChatGPT will surely give you some pointers. In such cases, you'll see the "Sign in with Google" button when you try to rerun the webapp.

For testing purposes, another way to force the "Sign in with Google" button to reappear is to run the app in an "incognito" window.

Display of the ephemeral will typically occur only after a considerable period, when Google decides it is necessary to confirm the webapp's association with a Google Account. It's not easy to trigger this for testing purposes, but I managed to generate the example shown earlier by creating a new Google profile and re-running the app.

Background on FedCM

Federated sign-on (or federated identity) emerged from enterprise and academic identity systems in the late 1990s/early 2000s. Instead of each system managing its own usernames and passwords, the idea was to share identities across systems that otherwise retained their own internal autonomy. FedCM is a browser-level evolution of these early ideas. It is Google (and others) saying

“Federated login is legitimate — let’s make it first-class and privacy-preserving.”

Development of the W3C FedCM standard has been ongoing since 2021 and has been controversial because it now aims to prevent IdPs such as Google and Facebook from silently tracking users across sites. Nevertheless, in 2024, Google Identity Services migrated “Sign in with Google” to FedCM by default in Chrome.

The key change introduced by the FedCM standard is that an IdP, such as Google, can no longer set a third-party identity cookie on an app when signing in a user. While the Google GIS library generates the "Sign in with Google" button, this is merely "decorating the doorbell". With FedCM in place, the browser owns the door, and Google's involvement occurs outside the app's "trust domain".

Sadly, under FedCM, marketing companies that pay to embed adverts in apps are still permitted to create third-party cookies. But because these don't contain full identifying information, they don't pose the acute risk of a third-party identity cookie. At the end of the day, one should perhaps remember that many useful websites rely on income from marketing to stay in business.

NgSysV2-5.3: An Introduction to the Google Cloud Shell

MartinJ — Mon, 06 Jan 2025 15:30:46 +0000

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

Last reviewed: Jan '25

1. Introduction

Would you like a free computer? How about one loaded with useful tools and lots of memory, one that is geared specifically to doing the sort of jobs you've been working on in this series? Interested? If so, please read on.

This series has recommended the use of Microsoft's VSCode IDE (Interactive Development Environment) as a general-purpose development "hub". As you know, this is the "Swiss army knife" of software that lets you:

create and edit source code
run terminal session to install libraries, start local servers and make deployments
use Git to commit changes to both local and remote repositories

But, while you've probably found this all perfectly satisfactory, let me remind you that nothing stands still for long in IT. A fresh wind of change is now blowing through the world of Interactive Development Environments.

Because your code is designed to deliver applications running out in the "Cloud," people have started to wonder why development source code isn't in the Cloud as well.

All three major cloud platforms—Google, Amazon, and Microsoft—now offer "Shell" products, which consist essentially of VSCode clones that run in your browser. The development code base is now stored remotely, and build/deployment workflows are closely integrated with their target server platforms.

Before you panic about learning a whole new set of editing procedures, let me assure you that these new IDEs look startlingly familiar — they just run in the browser rather than as independent local apps. You'll also be interested to hear that the services are free of charge.

This post describes, specifically, the Google Cloud Shell (GC Shell). Here's a list of its advantages:

No VSCode installation
No npm, Node.js or Git installation either - these tools are built into the GC Shell (along with many others)
Svelte projects can be deployed to services like Firebase Hosting or Google App Engine directly from the shell
You can work on your code without any preliminary preparation using any device that has a browser and network connection

If the GC Shell lives up to these claims, I imagine you'll easily see how it would have saved you a ton of time and trouble when you were working on your first webapp project. I'm also wondering why I ever bothered telling you anything different. Let's build a Svelte project with the GC Shell and see if the reality is as good as the hype:

2. Building a Svelte Project with the Google Cloud Shell (GC Shell)

You start the GC Shell in the browser by clicking its URL at ide.cloud.google.com. Actually, let me qualify that - in practice, it seems best to use a right-click and select "open in a new window". This then lets you use the F11 function key to switch the new window into full-screen mode. As you'll know by now, every bit of screen space is precious in an IDE. You won't want to waste any of this on a browser menu.

What happens now is rather magical. Assuming that you're logged into a Gmail account, Google now sets about creating a virtual computer for you somewhere up in the Cloud. This has up to 5GB of file storage for your code and configuration files (Firestore storage and CPU for a deployed webapp would be billed separately, as normal). Once activated, this "computer" remains permanently associated with your account. Sure, if you leave it unattended for 20 minutes or so, it will quietly close itself down, But once re-reference, your working environment is magically recovered like a desert rose after a shower of rain.

Naturally, the initial reference takes a little time - 20 seconds or so - and while this is going on, Google takes the opportunity to give you some background information about the GC Shell and then displays a Welcome screen headed "Learn the Essentials".

This offers opportunities for some initial configuration, too, but I think that you're likely to find that this just adds to your understandable confusion as a first-time user. My suggestion is that you leave everything alone here for now. There'll be plenty of opportunities to explore later.

Once things settle down, this is what you should see:

I hope you'll agree that this looks surprisingly VSCode-like. Down the left-hand side of the screen are all the familiar Explorer, Search, Source-control, Debug and Extensions tools. The Edit window itself is still open in the strange Welcome utility, but you can easily imagine this will become the panel in which you edit files. Below this, a terminal session has opened on your Gmail id.

Things will become even more familiar if you accept the Welcome panel's offer to "Open a Home Directory". This triggers another wave of GC Shell initialisation, after which (once you've clicked on the Explorer tool), the screen should look like this:

You've now got the beginnings of a working directory in the familiar column adjacent to the tools menu. A README.txt file is open in the editor panel, and you might like to edit this and confirm you can update and save it. The familiar main IDE menu bar is displayed at the top of the screen, too, so take the opportunity to use this to open a terminal panel. Once you've sized things to suit your usual working arrangement, I hope you'll agree that this looks very much like the familiar old VSCode arrangement.

The next job is to see whether you can use this to install, test and deploy a Svelte webapp. If you have read posts 2.1 and 3.6 in this series you'll remember that this was quite a procedure. Your new GC Shell system makes the job almost trivial!

The first task is to create a folder for the webapp. Open a terminal on the project root and enter the following commands:

mkdir my-svelte-app
cd my-svelte-app

Now install Svelte into this:

npm create vite@latest .

I'm using a Vite install here because it provides a generic tool for selecting Svelte from a long list of alternative Frameworks. You're also invited to add standard libraries, such as Tailwind. This way, you're less likely to forget essential steps in the procedure.

This Vite installation interface is very similar to the Svelte arrangement. The up/down and space keys are used to select items presented as lists, and the return key activates the selection. If you get stuck, be comforted by the knowledge that all you have to do is delete the my-svelte-app folder and start again.

For this particular experiment, you should select Svelte as the Framework and SvelteKit as the Variant. Then choose the SvelteKit minimal template and decline the offer to use Typescript (though it won't be long now before you will know enough about Javascript to appreciate why you will find this useful). I also suggest that you skip the opportunity to add development libraries to this experiment (though in other situations, I myself would certainly have chosen to add "eslint" and "tailwind"). Finally, choose "npm" as your package manager.

After one final "return", Vite completes the installation and invites you to launch the development server. Give it a try:

npm run dev

This should display the familiar terminal output:

> my-svelte-app@0.0.1 dev
> vite dev


  VITE v5.4.11  ready in 787 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Finally, then, a "ctrl-click" on the http://localhost:5173/ bit of the display should produce the reassuring "Welcome to SvelteKit" output of the barebones Svelte webapp.

So, that was a good start. Svelte is installed in your new Cloud Computer's workspace, and you can run a development server there. But now, can you use this to build and deploy a public version of the barebones webapp onto the web?

This seems quite a big ask, and, in fact, while there's nothing to stop you from launching an npm run build command right now, you'll find this concludes with the following warning message:

> Using @sveltejs/adapter-auto
  Could not detect a supported production environment. See https://svelte.dev/docs/kit/adapters 
to learn how to configure your app to run on the platform of your choosing

This is telling you that you haven't configured an appropriate Svelte adapter for your project. For Google App Engine targets, you need to install the @sveltejs/adapter-node adapter as follows:

@sveltejs/adapter-node

Then you also need to declare your use of "adapter-node" in your project'ssvelte.config.js file as follows:

import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter(),
  },
};

A build should now conclude successfully

Just three further points need to be covered before you can deploy your webapp.

First, you need to create an app.yaml file to direct the build. Here it is:

runtime: nodejs20

env_variables:
  NODE_ENV: production

Here, nodejs20 confirms that your webapp will run on Node.js version 20, the version currently recommended for App Engine use. Setting NODE_ENV to production optimizes the Node.js frameworks and libraries for performance and security.

Finally, you need to add the following line to the "scripts" section of package.json

    "start": "node build"

This tells App Engine to start the Node.js server on the content of your build folder.

You're now in a position to deploy your Svelte webapp with a command of the form gcloud app deploy --project=[project-id]

Here, [project-id] is the uniquely qualified ID of a Firebase project that you own. Ah, it's obvious really - how can you deploy to a project in the Google Cloud without telling gcloud which one it should use? But where will you get this from? Well if you've been following this post series from the beginning, Post 2.3 will have created a project name based on the root name "svelte-dev" - "svelte-dev-afbaf", say. Why not reuse this here? There's absolutely no reason why not. So, now deploy with the following command

gcloud app deploy --project=svelte-dev-afbaf

If all goes well, you should now be able to launch your webapp at https://.nw.r.appspot.com and see, once again, the familiar "Welcome to Sveltekit" message from the barebones Svelte webapp.

3. Wind-down

It might be worth sitting back for a moment and reflecting on what you've just done.

With little more than a click on a URL reference, you've just given yourself a top-class editor and a playground to run it in. Then you've used this to build a mini website and launched this onto the web where gentlemen in China could peruse it if they chose. None of this has cost you a penny and, if all went well, probably took you no longer than half an hour. I'd say that was a good morning's work by any standards.

More seriously, while this has been a very superficial introduction to Cloud Shells, I hope it has given you a taste of what is available. Clearly, there are some disadvantages to a browser-based IDE. Startup is noticeably slow and I shall be looking for ways of improving this. On the other hand, the close integration with the Cloud platform itself is likely to pay dividends. Some users are likely to be particularly interested in the possibility of using adapter-node to deploy a webapps to Google Cloud Run, as this has certain advantages over the older App Engine hosting.

For further details on the GC Shell, check out Google's documentation at Launch Cloud Shell

Footnote

If you've been following this post series closely, you may wonder why the GC Shell has enabled you to deploy with the official Svelte adapter-node generic node.js library rather than the community-supplied open source svelte-adapter-appengine used in Post 3.6. This is because GC Shell is tightly integrated with Google Cloud, abstracting many deployment complexities. Locally, you must manage those complexities yourself, and community adapters step in to bridge the gap. While there's absolutely nothing wrong with using the community adapter, some developers might be more comfortable using the official Svelte version.

Using Grammarly in Dev.to

MartinJ — Mon, 30 Dec 2024 10:43:05 +0000

1. Key Takeaway

If you're doing a lot of writing, Grammarly in Free mode will save you a lot of time. Using Grammarly in Pro mode will save you even more time and make your work more professional. It's worth every penny.
When you use Grammarly in Dev.to, one or two tricks will make your life a lot easier. Once you've got the hang of these, you won't want to write your posts any other way.

2. Grammarly - background

I've been using Grammarly for so long that I've almost forgotten I used to do all my spell-checking with a dictionary. Grammarly is now embedded in my Chrome browser as an "extension," and its design is so subtle that I barely notice that I'm using it.

Until last November, I used Grammarly in "Free" mode, which provided spelling checks and synonyms. But cunningly, Grammarly began highlighting chunks of my prose that it thought could stand some improvement. In my own case, this was most of it.

At first, I used this arrangement simply as a cue to shape up and try harder. Sometimes, this worked, and the highlighting would go away. But frustratingly, I often simply couldn't see what Grammarly was getting at.

However, sometimes, they would give me a "free ride" and show me their suggested improvements. This was almost always far better. So, in November, I took advantage of a "Black Friday" deal and snagged a 12-month license for just £60. They've got me for life now!

Working with Grammarly in "Pro" mode is a strangely warm, collaborative experience. Richard Brautigan's prophetic 1967 poem "All Watched Over By Machines Of Loving Grace" is never truer than when Grammarly has once again gracefully condensed four lines of my usual waffle into just two lines of lucid English.

3. Using Grammarly in Dev.to

In the past, I might have used a spell-checker extension in VSCode to build my markdown files. This method had the advantage of giving me a VSCode timeline facility that enabled me to back out changes when I messed up.

When I decided I wanted to switch to Grammarly, however, I had to leave VSCode behind and build my post using only the post-editing facility in Dev.to. This was fine, except that when I was doing some heavy editing, I found that continually toggling between Edit and Preview modes would make me dizzy. This was because when you enter Preview mode, the browser view resets you to the top of the file.

If you've been working at the bottom of a large post, scrolling down to recover the edit point makes your eyes boggle.

Fixing this would be a hard problem for the Dev.to the team, but I've developed my own workaround. It goes like this:

When working on a section that is going to require some heavy editing, I highlight a unique snatch of plain text at the top of the section (it's important to avoid markdown codes) and then ctrl-F this into the browser's text search pop-up.
Now I perform my edit, close the search popup and click preview. The page view will now reset to the top of the post
Finally, to recover my position and view my edit, I reinstate the search popup with another Ctrl-F and click the down arrow. The edit point is now back in view. Four clicks, and I'm done. After a while, it becomes automatic.

4. A Dev.to post "timeline"

It does worry me that I have no backup for my Dev.to posts. I'm pretty confident that dev.to won't lose the current version of a post but, from time to time, I find that it would be very useful to recover an earlier version. However, there's no post "timeline" in Dev.to.

A recent project saw me creating an "index" for a whole series of posts. You can see this at ngatesystems.com. A "curated" post series like this is useful in itself because it gives you two bites at getting your posts indexed by Google - once in Dev.to and once in your webapp. But, in this case, there's another benefit.

This is a pre-rendered Svelte project that creates an in-memory copy of the markdown for the posts referenced in the index. I use it in the webapp to provide a keyword search index for the post series.

The webapp itself is hosted on the Google Cloud App Engine and is rebuilt nightly using a Windows schedule. This is significant because Google retains deployment history so that, in an emergency, I can revert a faulty build.

Each of these deployments has, embedded within it, a snapshot of the markdown for the post state at that point. If I need a historic post, I can just temporarily reset the webapp to an appropriate point in the deployment history. Since the webapp is designed specifically to view the posts embedded within it .... Well, it's better than nothing ...

NgSysV2-10.1: Firestore CRUD templates

MartinJ — Tue, 26 Nov 2024 10:08:55 +0000

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

Last reviewed: Nov '24

Introduction

Google's extensive online documentation for Firestore CRUD (create, read, update, delete) instructions may be too detailed for everyday use. Here are templates for the most important Firestore functions. I suggest you cut and paste them as is and then replace the word "my" in variable names with some suitable contraction of the collection name that you're targetting. For example, references to a collection called "Lecture_events" might be coded as "lecEvtsCollRef".

Creating documents

To create a document containing a myDocData object with an automatically-generated id:

let myDocData =  .... create an object containing your data item properties .....
const myCollRef = collection(db, "myCollectionName");
const myDocRef = doc(myCollRef);
await setDoc(myDocRef, myDocData);

Note that, confusingly, Google Documentation on 'Adding Data' references an addDoc function as an alternative to setDoc. See the Postscript below for advice on why setDocis preferred.

In the code snippet above, the myDocRef= statement is the point at which an auto-id is allocated. If you need to find the value that's been assigned, you'll find this at myDocRef.id. Again, see the Postscript below for further information on this point.

To create a document with a data item as its identifier :

let myDocData =  .... create a data object  ..... 
let myDocumentIdentifier = .... create your identifier ....
const myDocRef = doc(db, "myCollectionName", myDocumentIdentifier)
await setDoc(myDocRef, myDocData);

Reading documents

To retrieve an individual document using its document id:

const myDocRef = doc(db, "myCollectionName", myDocId);
const myDoc = await getDoc(myDocRef);  
if (myDoc.exists()) {
  console.log("Document data:", myDoc.data());
}

To retrieve a selection of documents with selection and ordering criteria (example):

const myCollRef = collection(db, "myCollectionName");
const myQuery = query(myCollRef, where("myField1Name", "==", myField1Value), orderBy("myField2Name", "asc"));
const mySnapshot = await getDocs(myQuery);
mySnapshot.forEach((myDoc) => {
  console.log(myDoc.id, " => ", myDoc.data());
});

Within a Snapshot's forEach, the data for a document is available as myDoc.data(), the document's docRef is myDoc.ref and its docId as myDoc.id. If you're just interested in determining the existence of document(s) that match the selection criteria, a useful trick is to check for non-zero mySnapshot.size.

If you want to refer to individual documents in the snapshot array, you'll find the data for the n'th entry at mySnapshot.docs[n].data() and its id at mySnapshot.docs[n].id

Note that if you don't specify an orderBy field, documents will be returned in ascending order of docId. And if you include more than one where field, you must create a (compound) index. The browser inspection tool will help you here. You only need to follow the link in the "index-needed" error message. Individual fields are indexed automatically in a Firestore database.

To retrieve all of the documents in a collection:

const myCollRef = collection(db, "myCollectionName");
const myQuery = query(myCollRef);
const mySnapshot = await getDocs(myQuery);
mySnapshot.forEach((myDoc) => {
  console.log(myDoc.id, " >= ", myDoc.data());
});

Firestore comparison operators are "==", ">" , "<", "<=", ">=" and "!=", plus some interesting array membership operators.

To retrieve all of the documents in a hierarchy of collections and then do something:

You have to be careful when you want to perform a certain action after processing on a multi-level hierarchy of collections has concluded. If your code contains many nested foreach statements, each containing an await instruction, you can't rely on the individual awaits to tell you when the whole set has finished. Each of these individual awaits occupies a separate thread and these do not communicate directly with each other in any helpful way.

One way out of this problem is to use the traditional for loop on your snapshots rather than forEachs. Here's an example targeting all the children in a sub-collection before performing an action

const myParentsCollRef = collection(db, "myParentCollectionName");
const myParentsQuery = query(myParentsCollRef);
const myParentsSnapshot = await getDocs(myParentsQuery);
for (let i = 0; i < myParentsSnapshot.size; i++) {
    let myParentDocId = myParentsSnapshot.docs[i].data()
    const myChildrenCollRef = collection(db, "myParentCollectionName", myParentDocId, "myChildrenCollectionName");
    const myChildrenQuery = query(myChildrenCollRef);
    const myChidrenSnapshot = await getDocs(myChildrenQuery);
    for (let j = 0; j < myParentsSnapshot.size; j++) {
        console.log(JSON.stringify(myChidrenSnapshot.docs[j].data()));
    }
}

Here, you can rely on your awaits to be performed in strict sequence, and when you hit the end of the loop you know you can carry on confidently to perform your dependant action. But the performance hit created by this may be significant and so you might be interested in the following arrangement:

You can get a handle on the individual promises launched by the awaits in a forEach loop by storing them in an array. You can then apply an await Promise.all instruction to this array to find out when all its member promises are done. It is impossible to provide a simple template here to suit all circumstances, but the following is a "sketch" that illustrates the broad principles.

Here, a two-level hierarchy involving two separate collections (parents and children) is linked by a common parentsId field. The two collections are read into memory to permit analysis of the aggregate. This can only be done when all the children have been read.

const aggregateArray =[]
const parentsCollRef = collection(db, "parents");
const parentsQuery = query(parentsCollRef);
const parentsSnapshot = await getDocs(parentsQuery);

const promisesArray = [];
parentsSnapshot.forEach((parentsDoc) => {
  // for clarity, the nested awaits required to get the children for each parent are coded as an explicit function
promisesArray.push(fetchChildren((parentsDoc))  
})

// and here's the function itself
async function fetchChildren(parentsDoc) {
  const childrenCollRef = collection(db, "children");
  const childrenQuery = query(childrenCollRef, where("parentsId", "==", parentsDoc.data().parentsId));
  const childrenSnapshot = await getDocs(childrenQuery);
  chidrenSnapshot.forEach((childrenDoc) => {//push parent and children data into the aggregate array
  })
}

// and now you can perform your aggregate analysis. 
await Promise.all(promisesArray);

Updating a document

Example - to change the value of the myField property in a document's myDocData content

    const myDocRef = doc(db, 'myCollectionName', myDocId);
    await setDoc(myDocRef, {myField: myFieldValue}, { merge: true });

Example - to replace the entire content of document myDocId with a new object containing only a myField property

    const myDocRef = doc(db, 'myCollectionName', myDocId);
    await setDoc(myDocRef, {myField: myFieldValue}, { merge: false });

You can apply changes to several fields simultaneously by replacing the {myField: myFieldValue} bit in the above examples with an object containing the fields you want to change.

Deleting a document

    const myDocRef = doc(db, 'myCollectionName', myDocId);
    await deleteDoc(myDocRef);

CRUD operations within transactions

Inside a transaction, the patterns introduced above remain unchanged but the setDoc commands are amended as follows:

Within the runTransaction(db, async (transaction) => { ... }).catch(); function:

getDoc is replaced by transaction.get()
setDoc is replaced by transaction.set()
deleteDoc is replaced by transaction.delete()

Postscript

As mentioned above, Google provides addDoc() and updateDoc() functions for document creation and update in parallel with setDoc(). But this seems unnecessarily confusing when setDoc can perform both operations. Also, when it comes to transactions, addDoc() can only be used to create documents with auto ids. It seems simpler, in practice, just to use setDoc everywhere.
You may have noticed that there's no await on the doc(myCollRef) call that creates a Firestore document identifier. This tells you that Firestore somehow manages to do this without actually visiting the collection and seeing what is already in use. If you're curious about how it manages this you might like to check out the discussion at StackOverflow.

Google documentation references

Add data to Cloud Firestore : https://firebase.google.com/docs/firestore/manage-data/add-data
Read data with Cloud Firestore : https://firebase.google.com/docs/firestore/query-data/get-data
Delete data from Cloud Firestore : https://firebase.google.com/docs/firestore/manage-data/delete-data

SDK documentation can be found at:

NgSysV2-1.1: A Young Person’s Guide to Software Development in the Age of AI

MartinJ — Tue, 26 Nov 2024 08:13:31 +0000

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

Last reviewed: Mar'26

1. Introduction

Hello and welcome! I hope you find what you're looking for here.

This post is for complete beginners. It covers everything I wish I'd known when I first started tinkering with websites and databases. Maybe you're still in school, considering a career change, or retired but curious. What matters is that you have an open mind—one that's ready for new ideas and quick to spot opportunities. You'll need this because modern web development is a jungle of tools and techniques, and it's evolving fast. Where should you even start?

This series charts a path through that jungle—one that delivers quick results while building the skills you need to eventually go your own way.

The best part? Almost everything I describe here is free. Your only investment is time, and yes, that won't be insignificant. But as they say, "no pain, no gain!"

Here's the game-changer: you now have a powerful free ally in AI assistants like ChatGPT. This series includes some long posts with detailed instructions, but they'd be even longer if I explained every step in full. Now, if you get stuck or confused and need advice, just ask ChatGPT (or whatever alternative you favour). It'll give you clear, jargon-free answers instantly. This wasn't possible before 2022. Now it is, and it changes everything. See Post 4.1 for more on using your digital tutor.

But a word of caution. If you have your sights set on making a career in IT systems development, the landscape here is changing rapidly. Since Christmas 2025, almost all of my own JavaScript has been generated by ChatGPT. My contribution has been conversational English, telling the bot what I want it to do. My productivity has improved tenfold (likewise the quality of my systems, I'm ashamed to admit), but industry-wide, this translates into fewer opportunities for employment. The uncomfortable fact is that, while working in IT has become hugely more enjoyable, there are fewer vacancies for people whose only skill is in programming. The irony here, however, is that only those with a thorough understanding of system development technologies can sensibly direct a bot in system development tasks. How are these people to gain these skills except by learning the hard way and starting their careers as "grunt" programmers? This is the only way you will ever develop the knowledge and instincts required to "orchestrate" the development of an information system. If you still want to build a career as a systems developer, a course like this is exactly the right place to start. The financial rewards will be enormous, but be in no doubt that the competition will be ferocious.

So, warning delivered, let's get to it. Here's what this series aims to teach you and how we'll get there:

2. Objectives

The assumption here is simple: you want to develop software that reads information into a computer, processes it in a purposeful way, and displays the results on a screen. Oh, and on top of that, you’d like anyone, anywhere in the world, to be able to use your work.

Sounds straightforward? Unfortunately, in the world of IT, there are many ways to achieve this simple task — and choosing the right one matters!

In my experience, one of the simplest and most flexible approaches is to use an internet browser such as Chrome or Safari as the launchpad for your software. But, you might wonder: isn’t everyone using dedicated apps on their phones these days?

One key advantage of browsers is that they let your application run across every conceivable device — laptops, tablets, desktops, and phones — without worrying about hardware differences or operating systems. Browsers provide a sophisticated and practical environment for running your application logic. In contrast, native apps are tied to particular platforms and come with added complexity.

Another advantage is that browsers are already positioned on the Internet, whose whole purpose is to facilitate information sharing. This ubiquity is one reason major platforms such as Amazon and Facebook rely on browser-based interfaces to deliver their services worldwide.

The route I suggest leads to what is now generally known as a "web application" or webapp — a piece of software activated simply by entering the webapp’s address into a web browser. A modern webapp can maintain persistent data stores (“databases”) and provide security for that data via user login. ChatGPT itself is distributed as a webapp.

Before we dive into hands-on coding, here’s a brief look at the tools and technologies you’ll need to master to build a modern web application:

HTML (HyperText Markup Language) — the language used to structure and format content in web pages and web applications.
An IDE (Integrated Development Environment) — the editor used to write and manage code; in this course weu’ll be using Visual Studio Code (VS Code).
A programming language — the language in which you implement your application’s logic; we’ll be using the JavaScript programming language.
Browser developer tools — tools built into modern browsers for inspecting and debugging web applications; we’ll be using Chrome Developer Tools here.
A web development framework — a structured toolset that helps you build web applications efficiently; the framework we’ll use is SvelteKit.
A backend server platform — responsible for hosting the webapp, storing data, and running server-side code; we’ll be using Google Firebase on App Engine, which offers a particularly generous free tier.

In later posts, we’ll look in more detail at topics such as user authentication, databases, deployment, and security — all essential components of a real-world web application.

Since you’re reading this post online, I’ll assume you’re already reasonably accustomed to the online world. For simplicity, I’ve assumed you’ll be using a Microsoft Windows desktop or laptop, but you should be able to adapt these instructions if you’re on another platform.

OK. Buckle up - here we go!

2.1 HTML (HyperText Markup Language)

You’re developing software that displays text in a web browser. To control how that text appears — its position, size, colour, and emphasis — browsers rely on a system called markup. Markup works by surrounding text with special instructions, called tags, that tell the browser how to display the content.

You can try this out immediately using a simple text editor such as Microsoft’s Notepad.

Type the following line into your editor and save the file with an .html extension (for example, my-first-app.html):

<h1>Hello there</h1>

Now double-click the file. Your default web browser should open and display the words Hello there as a large heading. Congratulations — you’ve written your first webapp (albeit one that only you can see for now).

If this doesn’t work as expected, don’t get stuck. File associations and browser settings vary by device, so this is a good moment to ask ChatGPT for help. Describe what you’re seeing, and it can guide you through fixing the issue.

In this example, <h1> and </h1> are HTML tags. They tell the browser that the enclosed text should be displayed as a top-level heading. HTML includes many such tags, each with a specific purpose.

A good place to start learning HTML is Mozilla’s excellent guide:
Getting Started with the Web

Another popular resource is the interactive
W3Schools HTML Tutorial, which lets you experiment directly with HTML syntax.

You’ll also discover that tags can be qualified with additional instructions. For example, an <h1> tag can include a style attribute to change its colour:

<h1 style="color: red;">Hello there</h1>

These styling rules belong to a system called CSS (Cascading Style Sheets), which we’ll see in action shortly.

2.2 The IDE (Integrated Development Environment)

As you’ve probably guessed, even simple web applications quickly grow into large collections of files. Webapp code is verbose, and files containing hundreds or thousands of lines are entirely normal.

You could type all of this into a basic text editor like Notepad, but that approach doesn’t scale. Small mistakes — missing brackets, misspelt keywords — are easy to make and can be hard to spot. What you really want is a specialised editor that understands code and helps you write it correctly.

That’s the role of an IDE (Integrated Development Environment).

An IDE monitors your code as you type, highlights its structure, flags obvious errors, and often suggests or completes code for you. Used well, it dramatically reduces frustration and speeds up development.

There are many IDEs available, but the one I recommend is Visual Studio Code (VS Code). It’s free, widely used, and well supported by excellent documentation.

VS Code includes tools to format code consistently, detect syntax errors, and provide auto-completion for things like JavaScript keywords and variable names. As your project grows beyond a single .html file, it also helps you manage the collection of files that make up your application — what developers refer to as a project.

For example, VS Code lets you search and edit text across all files at once, undo changes by returning to earlier versions of a file, and run commands directly via an integrated terminal. These features become indispensable as your projects grow.

This is a good point to install VS Code and work through Microsoft’s short introduction:
Getting Started with Visual Studio Code

2.3 JavaScript

JavaScript is a good first programming language (and might possibly be the only one you ever need). It runs natively in the web browser, where it can read and modify the HTML that defines your web page — put simply, it can change what appears on the screen. It can also communicate with remote servers, making it useful well beyond simple visual effects.

JavaScript runs directly in the browser, with no separate compilation step, so you can edit code and see the results immediately. Your web browser itself acts as the JavaScript runtime (i.e., the interpreter that converts your code into the low-level instructions that actually display information on your screen).

Because HTML follows strict structural rules, the browser can build an internal representation of the page called the Document Object Model (DOM). JavaScript can access and modify individual elements within this model.

Let’s extend the my-first-app.html file you created earlier:

<h1 id="test">Hello there</h1>
<script>
let hourOfDay = (new Date()).getHours(); // 0–23
if (hourOfDay < 12) {
    document.getElementById('test').style.color = "blue";
} else {
    document.getElementById('test').style.color = "red";
}
</script>

This version makes the output depend on the time of day. Before midday, the text appears in blue; after midday, it appears in red. You’ve now written a simple dynamic web application. Congratulations - you're a programmer!

The <script> tags tell the browser that the enclosed content is JavaScript code. The expression new Date().getHours() returns the current hour (from 0 to 23). The if / else logic then uses this to decide which colour to apply.

If you’d rather not wait until lunchtime to test this behaviour, try switching the colour based on whether the current minute is even or odd. You can obtain the minute using getMinutes() and test for even numbers with:

if (num % 2 === 0)

The id="test" attribute on the <h1> tag gives that element a unique identifier. The call to document.getElementById('test') allows JavaScript to find that element and modify its style.

If you have any problems getting these heavily abbreviated instructions to work, just cut and paste the code from your file into ChatGPT and tell it what problem you're seeing. It will respond with an explanation of the necessary changes and a corrected version for you to paste back into your file.

You won’t spend your life writing document.getElementById(...) calls. Modern frameworks allow you to control screen behaviour using higher-level, more expressive patterns. In this series, you’ll use a framework called SvelteKit, which greatly simplifies this kind of work.

To become fluent in JavaScript, you’ll need a solid reference. The book I recommend is Eloquent JavaScript by Marijn Haverbeke. A physical copy is ideal, but the online version is also available. For browser-based learning, Mozilla’s tutorial on JavaScript basics is an excellent alternative.

Finally, start thinking about a small personal project to practise on. What data would it use? How would users interact with it? These questions will become increasingly important as you progress.

2.4 Browser Tools**

Your code won't work perfectly the first time. That's normal. Maybe the layout's off, or your logic has a bug. Sometimes the browser throws an error, sometimes it just sulks silently.

Your secret weapon: Browser DevTools

Every major browser has built-in debugging tools. In Chrome, just right-click anywhere on your page and select "Inspect." Boom—you're in.

Yes, it looks intimidating at first — a maze of tabs and panels. But trust me: once you learn the basics, you'll wonder how you ever coded without it. Full Chrome DevTools docs here.

What you can do with it:

Layout problems? The inspector shows you exactly how margin, padding, and width are affecting each element. You can even tweak values in real time and see instant results.

Logic problems? Set breakpoints in your JavaScript. Your code will pause when it hits them, letting you check variable values and step through line by line.

Code crashes? The console tells you exactly what went wrong and where.

Try it now: Open that my-first-app.html file from section 2.3, right-click, hit Inspect, and poke around. Change the colour in the Elements tab. Check the Console tab for any messages. Get comfortable — you'll be living here.

2.5 SvelteKit

In section 2.3, JavaScript interacted with the page using calls such as document.getElementById(...). While this works, it quickly becomes fragile and hard to maintain as applications grow.

Frameworks such as SvelteKit provide a higher-level interface to the browser’s DOM. Instead of manually locating elements and changing their properties, you describe what should happen, and the framework keeps the screen in sync with your data. This approach is known as reactivity.

For example, in Svelte, you can express logic such as “when popupVisible becomes true, show the popup”. When the value changes, the framework automatically updates the screen—no explicit DOM manipulation required.

During development, SvelteKit runs your application using a local development server started from the IDE’s terminal. As you edit your code, the browser refreshes automatically, giving near-instant feedback. This tight edit–refresh loop makes experimentation and learning much easier.

SvelteKit also allows you to control where code runs. Some logic executes in the user’s browser, while other logic can run securely on the server. You don’t need to worry about this distinction yet, but it becomes important when dealing with performance, security, and private data. SvelteKit is designed to make this separation clear and manageable.

When your application is ready, the framework “builds” it for deployment. This process bundles and optimises your code so that the deployed webapp is fast, compact, and efficient.

Many web frameworks exist, including React, Vue, and Angular. SvelteKit is a newer option, and I’m using it here because it offers a clean mental model, especially suited to beginners.

Svelte is the language that extends JavaScript and defines how components behave. SvelteKit is the framework that provides routing, server integration, and the overall application structure. You’ll be using both together throughout this course.

2.6 Firebase and App Engine

You can develop a complete webapp on a modest desktop computer. However, once you want other people to use it, you’ll need a specialist backend platform to support it on the web. This backend will:

Provide a public endpoint (a URL) from which your webapp’s files are delivered to users’ browsers.
Provide central storage for your application’s data, typically in a structured database.
Provide a secure environment for running sensitive or privileged parts of your application logic.

In this course, you’ll use two services from Google Cloud:

Firebase — an application development platform that provides tools such as Firestore, a simple and scalable cloud database.
App Engine — a hosting platform used to deploy your SvelteKit webapp and run its server-side code.

Because Firestore is used from the outset, your first step will be to create a Firebase account.

In the past, cloud services were often provided by traditional Internet Service Providers such as GoDaddy or HostPapa. These services still have their place and can offer excellent hands-on support. For modern web application development, however, cloud platforms such as Google Cloud offer a more flexible, integrated toolset.

3. Now Read on

This course is organised into two main stages.

In the first stage, you’ll learn the foundations: HTML, JavaScript, Firebase, and Firestore. If you’re new to web development, there’s a lot to absorb here, and it’s normal to feel unsure at times. Take it slowly, revisit sections as needed, and make active use of your chatbot tutor to unblock yourself.

The second stage introduces more advanced SvelteKit concepts and patterns. By the time you complete it, you’ll have the core skills needed to design, build, and deploy a genuinely useful web application.

The next step is to install SvelteKit on your local machine and get comfortable with the webapp development workflow. See Post 2.1 for instructions.

Keep smiling! This is all going to be just fine!

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

MartinJ — Tue, 26 Nov 2024 08:12:46 +0000

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

Last reviewed: Aug'25

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:

Create a Project
Install VSCode and open your Project within it
Open a terminal session
Install Node.js and npm
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 you 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.

AI-powered tools such as Warp now look set to displace the historically "geeky" nature of parameterised terminal commands with conversational English. I could get used to this!

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-package in 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," which 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.

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

npx sv create

As of November 2024, this launches a SvelteKit dialogue that walks you through configuring your project with Svelte 5. The px tool employed here is a "package runner" tool embedded within npm—it's installed automatically with npm.

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 (click the gear icon on the Firebase Console page for the project, select Project Settings, scroll down to the "Shut down" entry and proceed as directed). 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 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

And 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. 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 (forget any reference to git at this stage - you'll learn all about this later in Post 5.2). Give the command 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.

NgSysV2-2.2: Creating a simple Reactive Svelte webapp

MartinJ — Tue, 26 Nov 2024 08:06:26 +0000

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

Last reviewed: Feb '25

1. Introduction

The previous post created a Svelte webapp made up entirely of simple HTML. It didn't contain any Javascript and thus didn't use any of Svelte's sophisticated dynamic HTML generation facilities. This post will only scratch the surface of Svelte features but should give you a feel for the power of the language.

2. State and Reactivity

Viewed objectively, a webapp is a complex hierarchy of HTML pages, popups, tables, forms and buttons. This dizzying assembly of visual elements is "informed" by data. Tables are inflated with JavaScript array content. Popups appear and vanish at the behest of flag fields. Forms blossom with data when "poked" by mouse and keyboard input. In short - it's complicated. How can some sort of order be established over this situation?

Collectively, the body of data defining the appearance of a webapp at any moment in time is referred to as the webapp's state. Much effort has been expended on software development technology designed to make it easier to write webapps that react efficiently when state changes. Platforms like Svelte are expressly designed to deliver good reactivity.

Let's look at Svelte's approach to the definition of State and its implementation of Reactivity.

2.1 A simple reactive webapp

A common feature on a web page is a pop-up window that is displayed (usually annoyingly) when you start it up, but which then, obligingly, disappears when you click on it. Let's see how Svelte would let you use State and Reactivity to implement this in a webapp.

In Javascript, you need to define a variable before you can use it. So for example, a command like

myDataItem  = myDataItem  + 1;

will throw an error unless somewhere earlier in the code you had defined it using a statement like

let myDataItem;

As an aside, you'll find it useful to have access to a "playground" that lets you quickly try out bits of JavaScript like this. The "inspect" view of any browser page provides one such playground - open the inspector on a random page and select the "console" tab on its menu bar. Alternatively, you might try the javascript console at PlayCode.

There's lots to say about JavaScript's let keyword (try asking chatGPT about "scope") but let has an additional significance in Svelte because this is how you define State. In a Svelte program, any variable defined with let becomes part of the program's State.

So what? Well, I said earlier that State variables - variables that define the appearance of a webapp - are "reactive". This means that when their value changes, the appearance of the webapp is directed automatically to change accordingly. Suppose you use a popupVisible boolean variable to define the state of the popup. Could Svelte - a reactive platform - use the variable's value to determine whether or not the popup is visible? Let's try.

Here's the code I propose to use. I'll explain what it does in a minute:

//src/routes/+page.svelte - remove this line before running
<script>
    let popupVisible = true;

    function togglePopup() {
        popupVisible = !popupVisible;
    }
</script>

<div>
    {#if popupVisible}
        <button
            style="height: 6rem; width: 25rem; background-color: blue"
            on:click={togglePopup}>
        </button>
    {/if}
</div>

The code here is divided into two sections. The upper "script" section, defined by the <script></script> tags, declares a popupVisible javascript variable and a togglePopup() function. The lower "template" section, specifies HTML "moderated" by a Svelte {#if} {/if} logic block. Svelte code can reference variables and functions defined in the <script> section to guide HTML code generation. References are enclosed by curly {} brackets, except when they're used directly within a logic block - see Svelte docs at Basic Markup and Logic Blocks for full details.

The code displayed above is very crude. A "pop-up" is normally defined by a <div> tag formatted with a border and some positioning CSS. Here I've used a <button> tag - something that would be more commonly used to define the "submit" element on a form. I've done this simply because it enables me to avoid some technicalities that might distract you. I've coloured the button "popup" blue so that you can see it.

If you still have a copy of the skeleton svelte-dev Svelte project created in Post 2.1, try using this code to replace the entire content of src/routes/+page.svelte. When you open a terminal on the project and start the dev server as before, your browser should now leap into life and display the screen shown below:

The blue rectangle is the "pop-up". It is displayed at startup because at this point the popupVisible variable is set to true and the Svelte logic driving the page's HTML generation is instructed to create a <button> tag in this case.

Now try clicking the pop-up. Magic! It disappears. This is because the <button> tag specifying the popup contains an onClick clause that makes a click on the element run the togglePopup function. This in turn sets the popupVisible variable to false.

I said earlier that changing a Svelte "state" variable causes Svelte to refresh the screen by re-running the page's template section. So, the template section re-runs and now, since the value of popupVisible is false, the <button> code displaying the pop-up is bypassed leaving an empty page.

Take a moment now to let this sink in. If you'd still been working with the primitive DOM-manipulation code I introduced in Post 1.1 this effect could only have been achieved by writing a good deal of fairly technical (and probably rather inefficient) low-level code. Here, you've just had to change the value of a variable. Sveltekit has handled the intricate consequences automatically (and, rest assured, efficiently).

In short, Svelte gives you a high-level language that lets you leave the tedious details of browser screen management to the framework.

In October '24, Svelte 5 introduced a series of refinements to its reactivity-definition arrangements. The let construct described above still works fine for everything in this post series, but a new runes concept is now available to handle more complex requirements. See What are Runes for details.

2.2 Data Input

Let's make the pop-up a bit more interesting. Imagine that you had the job of maintaining a "products" list for a manufacturing company. You'd want a utility that displays the current list and enables you to add new products. In practice, of course, you'd also want it to be able to edit and delete entries, but let's keep things simple for now.

Have a look at the following code. It will probably stretch your JavaScript knowledge but the internal comments should help.

//src/routes/+page.svelte - remove this line before running
<script>
    let popupVisible = false;
    let newProductNumber = "";
    let products = []; // An array of product objects {productNumber: productNumber}
</script>

<div style="text-align: center">

    <h1>Inventory Maintenance Page</h1>

    {#if !popupVisible}  <!-- the start position - popup not visible-->

        <p>Currently-registered Product Numbers:</p>

        {#each products as product}  <!-- display the current list of  product numbers-->

            <p style="margin: 0">{product.productNumber}</p>
        {/each}
        <button
            style="margin-top: 1rem"
            on:click={() => {
                // a function to toggle the popup on
                popupVisible = true;
            }}
            >Add Another Product
        </button>

    {:else}   <!-- display the product registration form-->

        <div style="border:1px solid black; height: 6rem; width: 30rem; margin: auto;">
            <form>
                <p>Product Registration Form</p>
                <label>
                    Product Number
                    <input bind:value={newProductNumber} />
                </label>
                <button
                    type="button"
                    on:click={() => {
                        // a function to add the product number to the array and hide the popup
                        products.push({ productNumber: newProductNumber });
                        popupVisible = false;
                        newProductNumber = ""; // Clear the input field
                    }}
                    >Register
                </button>
            </form>

        </div>
    {/if}
</div>

The "template" section here begins by checking the value of popupVisible. If this is false (which it will be on startup because the variable has just been initialised in the "script" section), the webapp displays the webapp's current list of "products" (an array of productNumbers stored in a products array).

The code now move on and displays an "Add another Product"button - a normal one now, not the freakish version used in the previous example. But, as before, it has an associated on:click function, and this one sets the value of popupVisible to true.

What will happen if the button is clicked? Why, since popupVisible is a reactive variable, the webapp will refresh its screen.

This time, the products-display section of the form is ignored and control will move straight to the second part of the template section.

Here, you'll see something more like a conventional popup. This one uses a <form> tag within a container div> to collect input for a newProductNumber state variable. A special Svelte "bind" qualifier" is employed here here to synchronize newProductNumber with the user's keyboard typing. Every time the user types a character into the form's <input> field the newProductNumber is updated.

When the user finally clicks the form's "Register" button, its on:click function is thus able to push a fully-updated newProductNumber into the products array and reset the popupVisible field.

Finally, since popupVisible is a reactive variable, the "template" section of the code re-runs and the popup is replaced by the updated list of product numbers.

One or two other things may puzzle you. In the previous example, anon:click qualifier referenced a function defined in the webapp's <script> section. In this new version of +page.svelte, however, the function is defined explicitly within the <button> field's HTML spec. Both approaches are perfectly valid. The version used here probably looks a bit strange to you, but it is a widely-used arrangement that has the advantage that the function's logic is defined at its point of invocation. This makes it much easier to see what's going on.

For reference, the expression:
"() => { .... }" is saying "here's a function defined by the following JavaScript statements: "{ .... }". There are many variants. Ask chatGPT to give you a tutorial on "arrow" functions .

Moving on, you'll also note that I've been much more adventurous with my "styling". There's a heading, for example, and everything is nicely centred (CSS "inheritance" ensures that the style="text-align: center" of the enclosing <div> is also applied to everything within the <div> block). Then there's the horrific style="border:1px solid black; height: 6rem; width: 30rem; margin: auto;" attribute applied to the <div> tag enclosing the Registration form. Ask chatGPT for a description of what this does. A tutorial on the "border box" model might be handy too.

But that's enough background. Let's see the webapp in action. Paste the new code over the current content of your +page.svelte file, save it and (if necessary) open a terminal on your project and restart your dev server with the npm run dev -- --open command. Here's what you should see in your browser::

And here's what you should see when you click the button:

Since there's no validation on the newProductNumber field, you will find that you can enter characters as well as numbers - we'll fix this in a future post. Even so, when you click the "Register" button, you should see the popup replaced by the original Inventory display page, with your new product "number" added to the list.

This scrap of Svelte is almost starting to look like an information system!

3. Onward and Upward

This post has given you a brief glimpse of the key concepts embodied in the Svelte language. Unfortunately, there's a snag. As I'm sure you will have noticed, the "Inventory" example you've just seen is effectively useless because every time you close the webapp its product list disappears! The next step, therefore, is to introduce you to Google's Firestore database technology. This will let you create persistent storage on a server host.

Postscript (a): When things go wrong - Investigating Layout issues with the Chrome Inspector

"When things go wrong" in Post 2.1 described how to handle some of the grosser problems you'll encounter when developing a webapp. But now that you're working at a more advanced level you need a more sophisticated tool. This section introduces you to the "Chrome Inspector", an invaluable aid when correcting problems with your webapp's screen layout and logic errors in your JavaScript (and much more besides, as you'll see later in this series).

The Inspector is launched on a webapp Page by right-clicking on the page and selecting the "Inspect" option. Here's an example of its output:

In this screenshot, I have:

Launched the Inspector, as above. wThe Inspection Window is now hiding the bottom half of the webapp window. This can be inconvenient because the Inspector may now be hiding some webapp elements that I want to inspect! This is partially handled by "sizing" the inspector window by clicking and dragging on its upper border. Alternatively, you can the "Dock Side" tool under the triple-dot icon on the extreme right of the menu to dock the Inspector to the side of the screen.
Selected the "Elements" tab from the Inspector's menu bar
Expanded the <body> and <div> lines in the HTML tag hierarchy displayed in the left-hand inspection panel and moused over the <h1> tag showing the webapp's heading

If you try this yourself, you'll note that the heading has acquired some coloured graphics. These show you the size and position of the margin, border and padding that have been added to your text. The right-hand inspection panel provides more detail. If you click the computed tab in its menu, you'll get a graphic that explains the colour coding and detailed sizings for the various elements. If you click the "styles" tab you'll see details of the styles attached to the text. The first set of entries in the list confirms those styles set explicitly with the tag's style= clause (none in this case). After that, you'll see any styles inherited in other ways.

The beauty of this panel is that you can use the inspector to see the effect of changing and adding styles. For example, suppose you wanted to try out a red font on the heading, click somewhere in the element.style entry at the top of the panel and enter color: red. The heading, obligingly, now turns red. Note the opportunity to use autocompletion to try out different colours.

I don't want to labour the point, but I think you should be starting to see how this facility can give you a precise and intuitive tool for investigating and fixing layout issues. For more information check out Google's documentation on the inspector at DevTools.

Be prepared to spend quite some time on this. The Inspector is a complex tool so it will be a while before you can use it confidently. But this will be time well spent. The Inspector has certainly saved me countless hours of blind experimentation with source-code settings. The inspector's graphic display makes visible all the hidden properties of element widths, margins and padding.

Postcript (b): Investigating Logic issues with the Chrome Inspector

The Inspector can also help you find logic errors by enabling you to view your source code and set "breakpoints" on lines where you would like execution to halt. After refreshing the webapp (with the Inspector still open), you can inspect field values at each breakpoint. Here's a screenshot of the Inspector in action:

In this screenshot, I've:

Launched the Inspector as before.
Clicked the "Sources" tab above the left-hand panel and expanded the source hierarchy for localhost in the page view to enable me to click on the italicised +page.svelte entry for my route in the src/routes line.
Noted that the right-hand panel now displays the source for +page.svelte and clicked on the let popupVisible = false; line to set a breakpoint (confirmed by a blue highlight on its line number).
Refreshed the page in the browser and noted that the webapp is now displaying a "paused in Debugger Message" that includes a "Resume execution" button and a "Step over next function call" button. You'll also see that the let popupVisible = false; line is now highlighted

The effect of all this has been to put the webapp into "code debug" mode. Right now, I'm debugging the <script> section of the webapp, which is a bit pointless since it only runs once and you know exactly what it does. But let's go through the motions because they'll help you get a feel for what the debugger can do for you in JavaScript source code.

Currently, the webapp is halted before execution of the first statement and so hasn't done anything useful. But advance to the next statement by clicking the "Step over next" button and note that the highlight has now moved to the second line. Mouse over the popupVisible field in the first line and note that a tooltip is now displayed showing its current value - false, of course. Repeat the trick to confirm the settings of newProductNumber and products.

The value of the Inspector is more clearly seen if you set breakpoints in Javascript functions defined in the <script> section. These run every time the function is referenced and the Inspector is great for tracking progress through these.

Unfortunately, debugging with breakpoints in the "template" section of a +page.svelte file isn't so straightforward. Here, the code runs every time the page re-renders following a change in a reactive variable, but the code that the "sources" tab displayed here (ie the original Sveltekit code of your +page.svelte) is not what is now actually running. The original code has been replaced by Svelte scripts generated by the local server. Consequently, there's only limited scope for you to get information about what is happening.

If you want to know more about the rendering process and why your +page. svelte file behaves like this in the Inspector, skip across briefly to the end of Post 4.4. But, be warned, it's complicated!

In my experience, you can usually set breakpoints on Sveltekit statements and thus track the path taken during a re-render. But these won't display field values.

You can, however, usefully set breakpoint in embedded functions. For example, try setting a breakpoint in the products.push({productNumber: newProductNumber}); line for the "Register" button. Note that the entire block of <button> code gets highlighted (in grey) reminding you that this is an "anonymous function" (get chatGPT to explain this to you sometime). Now rerun the webapp and observe how the breakpoint behaves just as it did in the <script> section. Having asked the webapp to register a newProductNumber of 123 and clicked the "Register" button you'll see the webapp halt on the breakpointed line. "Step over next function call" and mouse over the products.push({productNumber: newProductNumber}); line. You'll note that it now shows you that the products array now contains the single value 123.

If all else fails and you still need to check the value of a variable in the template section, try adding something along the lines of <p>Value of x is {x}</p> statement (where, I'm sure you'll understand, "x", is the reactive variable you want to monitor).

Note that the buttons on the "Paused in debugger" line are duplicated in the Inspector menu bar and are supplemented by a "Step into next function" button to enable you to traverse nested functions.

As you'll quickly realise, breakpoint settings persist in webapp files. Breakpointed lines are toggled off by clicking them again. A "right-click" in the entry for a file in the Inspector's "Breakpoints" panel on the right of the screen will reveal a master toggle to remove all breakpoints.

Finally. note that when a webapp hits a major problem and "crashes", opening the Inspector will reveal a red "error count" at the right-hand end of its menu bar. When this happens, details of the problem can be viewed in the Inspector's "console" tab.

NgSysV2-2.3: Creating a simple Svelte Information System with Google's Firestore

MartinJ — Tue, 26 Nov 2024 08:05:33 +0000

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

Last reviewed: Feb '25

1. Introduction

Most webapps exist purely to create and access shared information. Consider, Amazon's https://www.amazon.co.uk/ website. The essential purpose of this system is to let you browse a central collection of product details, place orders and monitor progress on delivery. To make this work, Amazon must:

Maintain this information somewhere accessible over the web
Structure and manage it to ensure near-instant access and total integrity.

This post is all about the "database" technology used to achieve these aims.

Warning - this is a long post because database reads and writes in Svelte draw you remorselessly into using SvelteKit's client-server architecture. Previously, your code ran exclusively "client-side" in your web browser. Now you'll also be running code on the local server launched by npm run dev. This has consequences...

I've looked at ways of splitting the post up but they don't work. To make matters worse, the Javascript you'll use contains many new features. So, I'm sorry - you're just going to have to suck it up.

But look on the bright side. Once you're through this, things will start to get easier. Take it slowly. Use chatGPT where you feel I've not explained something clearly. You'll find the bot particularly helpful when you need advice on JavaScript syntax. Relax. This is going to be fun!

2. Configuring your project to use Google's Firestore

There are innumerable ways of storing shared data on the web. This post series uses Google's Firestore system because it suits beginners. It requires minimal setup and fits comfortably within the structure of a Svelte webapp.

You'll need to perform four initial steps:

Obtain a Google account
Create a Firebase project under this account
Register your "webapp"
Initialise a Firestore Database for your Firebase project

Firebase is Google's umbrella term for many different services you might use to mount a simple project on the web. The services for a given account are managed via Google's "Firebase console" at https://console.firebase.google.com/. They include both a "Storage" service that enables you to upload files into the Google Cloud and a "Firestore Database" service. A database differs from a file in that it possesses a configurable structure. It enables you to access and update discrete elements of the configured data set.

2.1 Obtaining a Google account

If you have a Gmail address, you're already covered because this automatically counts as a Google account. If you don't, follow the instructions at Create a Google Account to get one.

If you find system development work addictive, you'll quickly find yourself managing multiple projects. You'll then find it useful to create separate accounts for each of these. In IT work, account keys are your most precious possessions. It makes sense to maintain firewalls between projects by giving each project a separate account, each secured by a different password.

2.2 Creating a Firebase project for your code

Launch the Google Firebase console and log in with your Google Account (noting that, if you're logged into Gmail with this, you're already logged into the Firebase Console as well). Now click the "Create a Project" box to launch the process.

Google will want you to supply a name for your project (I suggest you use the project name you're using in VSCode), and will propose an extension that makes this a unique "Project Identifier" within the Firebase world. So for, example, my version of the "Svelte-dev" project used in this post series is known to Google as "Svelte-dev-afbaf".

As an aside, since the Project Identifier will ultimately form part of the default live URL for your webapp, and since Google lets you edit its initial "uniqueness extension" proposal, you might be tempted to try to change this to something meaningful. However, I suggest you forget this idea. Firstly, you'll find it difficult to pick an identifier that suits both parties. Secondly, in my experience, these "default URLs" aren't ever indexed by Google. A "custom URL" purchased at minimal cost and linked to your default URL when you go live is by far the best way to get a memorable URL.

Now click "Continue" to reveal a "Google Analytics" registration page. You can safely ignore this here as it is relevant only to performance issues on live apps. Use the slider bar to decline it and click the "Create Project" button to continue.

The lights now dim a little as Google registers your project. Finally, once you've clicked one more "Continue" button, you'll find yourself in your project's Firebase Console window. Here's a screenshot of the Firestore tab for a "svelte-dev" project:

It's worth giving yourself a moment to familiarise yourself with this page because it is a little complicated. The basic structure consists of a "tools menu" on the left that determines what gets displayed in the main panel on the right. The problem is that the menu is "adaptive" and maintains a "Project shortcuts" section that remembers where you've been. Consequently, the menu seems to look different every time you open the console! Once you've grasped this feature, however, things work well. Note that the complete set of tools is hidden within the "Build", "Run" and "Analytics" submenus of their parent "Product Categories" menu item. The "Build" set contains everything you need at present.

Before you proceed further, note the following:

information at the top of the screen confirms that the svelte-test project is currently registered on the "Spark" plan. This means that everything you're doing at present is free. Eventually, in this post series, you will get to a point where you need to start to paying Google, and will need to upgrade your project to the "Blaze" tariff. But don't worry - this is a long way off yet, you won't pay much, and you can create a monthy budget to limit the amount Google might try to charge you.
project details are revealed by clicking the "Project Overview" button at the top of the toolbar. Details available here include a reminder of the Project Identifier and a button to delete the project. If everything goes wrong, you can always use this to rub out the mess and start over again. This won't cost you anything

2.3 Registering your webapp

Firebase needs to know what your webapp will be called:

Click the </> icon below the "Get started" message and supply a nickname when requested. I suggest you use your project name again here (eg "svelte-dev").
Ignore the offer to "Set up Firebase Hosting for this app" because, when we finally get around to deployment, all your hosting needs will be handled by App Engine.
Finally, click "Register" and "Continue to the console" to return to the initial console screen.

2.4 - Initialising a Firestore database

Select "Firestore Database" from the "Build" stack in the tools menu to obtain the Firebase console view shown below:

Once you've clicked the "Create Database" button, the console will want you to:

Set your database "Name and Location". "Name" is the identifier for the database and will only be relevant if you plan to create several different databases in your project. Leave this empty, for now, so that Google uses its "default" setting. "Location" specifies where your database will be physically located. The pull-down list of options available here is possibly your first sight of the scale of the Google Cloud service. Its server farms are available right around the globe. You will probably want to select a server close to your location. For example, I generally use "europe-west2 : Heathrow" since I am based in the UK. Pages elsewhere in the Google Cloud console enable you to specify performance and availability characteristics, but you don't need to look at these for now.
Secure your database with "Rules". The screen here offers you a choice between setting initial "production" and "test" "rules". This only makes sense, of course, if you know what "rules" are in the first place - and this isn't the right time for me to explain them. Unless you know better, I'd like you to check the "test mode" option here. Be assured, I'll come back to this later when I talk about "authorisation" (and, oh boy, is there a lot to talk about!).

Once you're through these two stages, the Cloud Firestore page opens in the Firebase Console. What now?

3. Working with a Firestore Database

This section aims to answer the following questions:

What is a database?
What does a Firestore database look like?
How can I initialise a database in the Firestore console?
How can I access a Firestore database in Javascript?
How can I get a Svelte +page.svelte file to load data from a Firestore database?
How can I get a Svelte +page.svelte file to add data to a Firestore database?

3.1 What is a database?

For our immediate purposes, a database is a set of tables containing rows of values for named data "fields". So, for example, a Customer Order" database might contain

a "Customers" table full of "Customer Id" and "Customer Address Details" field values
a "Products" table full of "Product Number" and "Product Detail" fields
a "Customer Orders" table with details of the orders for a "Product Number" placed by a "Customer Id"

The important thing is that such an arrangement is structured with consistent standards for the naming and formatting of data content

3.2 What does a Firestore database look like?

In Firestore, tables are called "collections" and rows within them are called "documents". Documents stored within a collection aren't all required to have the same fields, but field names and content are expected to follow consistent patterns throughout the collection.

An important feature of a Firestore document is that it should have a unique identifier or "key". Sometimes there will be a field such as "Email Address" within each document that you can use to provide a "natural" unique key. If not, Firestore can be asked to create an artificial key automatically.

Database design is probably the most challenging part of system development and, once again, I will duck this because the issues involved will only become clear when you've had some practical experience. However, when you have a moment, you will find it useful to check out the Cloud Firestore Data model page.

3.3 How can I initialise a database in the Firestore console?

In this post, I plan to show you how to create a single products collection in your default Firestore database. This will contain simple documents containing a product number field with a key automatically generated by Firestore.

On the Firestore page on the Firebase console, click the "Start collection" button and enter the name "products" in the "Collection ID" field of the popup that now appears.

Now use the data entry page to create a test products document containing a "productNumber" field with a numeric value of "1" and a "productDetails" field with a text value of "Product 1".

Type "productNumber" in the "Field" entry box to set the field name, set the "Type" box to "number" and enter "1" (without the quote characters) in the "Value" box.
Click "add field and type "productDetails" in the "Field" entry box to set the field name, leave the "Type" box set to its default "string" setting and enter "Product 1" (without the quote characters) in the "Value" box.

Now sign off the document by first clicking the "Auto Id" button and then "Saving" it Here's what the console should look like now:

If you wanted to add further documents, you would click "add document" at this point, but that's not necessary in this case - you only need a single document to demonstrate your webapp's ability to read it.

You're finished here for now, but note that the console's "panel view" lets you edit or delete the document you've just created. If you've got in a complete mess you can even delete the entire collection and start again.

3.4 How can I access a Firestore database in Javascript?

Here's where things start to get really interesting!

Google provides a library of Javascript functions to let you read and write Firestore documents. Such libraries are referred to as "APIs" (Application Program Interfaces). Have a look at the following code that shows how the firebase/firestore library would be used to read all the documents in svelte-dev's products collection:

import { collection, query, getDocs, orderBy } from "firebase/firestore";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

const firebaseConfig = {
    apiKey: "AIzaSyCE933 ... klfhFdwQg1IF1pWaR1iE",
    authDomain: "svelte-dev-afbaf.firebaseapp.com",
    projectId: "svelte-dev-afbaf",
    storageBucket: "svelte-devt-afbaf.appspot.com",
    messagingSenderId: "1027 ... 85697",
    appId: "1:1027546585697:web:27002bf ..... b0f088e820",
};

const firebaseApp = initializeApp(firebaseConfig);
const db = getFirestore(firebaseApp);

const productsCollRef = collection(db, "products");
const productsQuery = query(productsCollRef, orderBy("productNumber", "asc"));
const productsSnapshot = await getDocs(productsQuery);

let currentProducts = [];

productsSnapshot.forEach((product) => {
    currentProducts.push({productNumber: product.data().productNumber});
});

return { products: currentProducts } // accessed in +page.svelte as data.products

Concentrate on the section that starts const productsCollRef = collection(db, "products");. This uses Firestore API calls to load a sorted copy of all documents within the products collection into the State currentProducts variable.

First, the collection and query functions, drawn from the Firestore Client API library, are used to point Firebase at the products collection and define a query to run on it. Then the query is launched by a getDocs API call.

I won't attempt to describe the mechanics of this sequence of Firestore API calls. Treat these as a piece of "boiler-plate code" - code - the sort of thing that you write once and, ever afterwards, simply copy. Since you'll find you need a whole library of templates to cover the full array of Firestore "read", "update" and "delete" operations, you might find it useful to look at "Firestore CRUD command templates" in Post 10.1. If you'd like to check out Google's own description of the API, you'll find links to these at the end of Post 10.1.

"CRUD" here is short for "create", "read", "update" and "delete".

The getDocs result is returned as an array of documents conventionally called a "snapshot". However, note that the getDocs function call is preceded by an await keyword.

The await keyword is needed here because, by default in Javascript, instructions referencing external data sources that may take an unpredictable time to complete are handled asynchronously. The "await" keyword essentially (though this is a gross simplification) enables you to override this arrangement. When you have more time, you might find it useful to have a look at Post 5.1

But right now, returning to our code snippet above, look at the section starting with the const firebaseConfig statement.

The firebaseConfig declaration initialises an object containing the configuration details needed to connect your web app to your specific Firebase project. It includes various keys and identifiers that Firebase uses to locate and authenticate your app. You'll find the settings for your particular webapp in "Project Overview/Project settings" on the Firebase console. The firebaseConfig settings in the code samples below have been "obfuscated" because they are unique to my project and aren't to be passed around lightly (more about this shortly). When trying the sample code below, you'll need to copy in the firebaseConfig settings from your own project.

With firebaseConfig initialised, the webapp can initialise the db variable required by the query's const productsCollRef = collection(db, "products"); statement:

const firebaseApp = initializeApp(firebaseConfig);
const db = getFirestore(firebaseApp);

Finally, you may be wondering where these API functions come from. The answer is that they are imported from locations in your project by the three statements at the top of the code block:

import { collection, query, getDocs, orderBy } from "firebase/firestore";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

Here "modular libraries" are being accessed to supply functions for your code. Named functions such as collection are extracted from a parent module to fulfil the references required later in the code.

But then this leads to the question "And how do modular libraries get into my project in the first place?" The answer, of course, is that you have to put them there, and the tool you use to do this is faithful old npm.

Back in a VSCode svelte-test terminal session (terminate the dev server if necessary with a couple of ctrl-C keystrokes) and run the following instruction'

npm install firebase

After a minute or two (the installation involves a sizeable download), you'll be poised to run code that downloads a Firestore database collection. But, you still don't know how to embed this in a Svelte webapp. So, on to the next question...

3.5 How can I get a Svelte `+page.svelte` file to load data from a Firestore database?

This has been a long haul but, hang in there, you're nearly finished.

Currently, in the <script> section of your src/routes/+page.svelte file, you have the following statement:

let products = [];

As you know, this declares your products field as a State variable and initialises it as an empty array. What you want to do now is replace "empty" with the content of the products Firestore collection.

Unfortunately, as you've seen, this involves an asynchronous operation. This complicates things somewhat because Svelte doesn't want anything to slow down the initial load of a page - it's happy to see information added later but, the first user impression should be of an instantaneous response. Svelte has a standard arrangement for loading initial data into a +page.svelte file. It goes like this:

First, you create a new src/routes/+page.server.js file that wraps all your asynchronous code inside a load() function (mandatory name) and returns its results as an object.

Here's the code

// src/routes/+page.server.js
import { collection, query, getDocs, orderBy } from "firebase/firestore";
import { initializeApp, getApps, getApp } from 'firebase/app';
import { getFirestore } from "firebase/firestore";

export async function load() {

const firebaseConfig = { // replace with settings from your own project!!
    apiKey: "AIzaSyCE933v....vklfhFdwQg1IF1pWaR1iE", // obfuscated code
    authDomain: "svelte-test-afbaf.firebaseapp.com",
    projectId: "svelte-test-afbaf",
    storageBucket: "svelte-test-afbaf.appspot.com",
    messagingSenderId: "1027 ..c585697",
    appId: "1:1027546585697:web:27002bf  ...ccccb0f088e820", // obfuscated code
};

// see Post 3.3 for an explanation of the "ternary" expression used below
const firebaseApp = !getApps().length ? initializeApp(firebaseConfig) : getApp();
const db = getFirestore(firebaseApp);

const productsCollRef = collection(db, "products");
const productsQuery = query(productsCollRef, orderBy("productNumber", "asc"));
const productsSnapshot = await getDocs(productsQuery);

let currentProducts = [];

productsSnapshot.forEach((product) => {
    currentProducts.push({productNumber: product.data().productNumber});
});

return { products: currentProducts }
}

The load function above returns an object with a single products property whose value is the currentProducts array constructed by the Firestore API calls.

This is all very well, but how is this to be conveyed to the products state variable in +page.svelte?

The first step is to advertise a new data (mandatory name) state variable as a prop (short for "property") of +page.svelteYou do this by declaring it with an export keyword, thus:

export let data;

Props won't be covered in this series until you get to Post 3.1 and learn about "components". For now, think of your +page.svelte file as a function with data as its parameter.

When you run your +page.svelte file now, the SvelteKit framework sees the export let data declaration with its reserved data keyword and thinks, "ah, I need to run the load() function associated with this page". The products data is duly returned into the data prop of +page.svelte and now, since this is a reactive variable, the page is refreshed.

All you need to do to make your existing "template" code work with the new arrangement is to replace products references with data.products

The +page.server.js file is your first sight of "server-side" code in Svelte - that is, code that runs in the server. All the +page.svelte code you've seen so far runs "client-side" in the browser. A +page.server.js file, by contrast, runs either in the local server launched by npm run dev or, after deployment, in the Node.js environment of an App Engine server. Server-side code runs faster than client-side code and is secure. The only person who can view or change it is you - its owner.

Here's the complete code for a modified version of the +page.svelte file from Post 2.2:

// src/routes/+page.svelte - remove before running
<script>
    let popupVisible = false;
    let newProductNumber;
    export let data; // An array of data.product objects returned by +page.svelte.js
</script>

<div style="text-align: center">
    <h1>Products Maintenance Page</h1>
    {#if !popupVisible} <!-- the start position - popup not visible-->

        <p>Currently-registered Product Numbers:</p>
        {#each data.products as product} <!-- display the current list of  products-->
            <p style="margin: 0">{product.productNumber}</p>
        {/each}
        <button
            style="margin-top: 1rem"
            on:click={() => {   // a function to toggle the popup on
                popupVisible = true;
            }}>Add Another Product
        </button>

    {:else} <!-- display the product registration form-->

        <form
            style="border:1px solid black; height: 6rem; width: 30rem; margin: auto;"
        >
            <p>Product Registration Form</p>
            <label>
                Product Number
                <input bind:value={newProductNumber} type="text" />
            </label>
            <button
                type = "button"
                on:click={() => { // a function to add the product number to the array and hide the popup
                    data.products.push({productNumber: newProductNumber});
                    popupVisible = false;
                    newProductNumber = ""; // Reset the input field
                }}>Register
            </button>
        </form>

    {/if}
</div>

If you now replace the contents of your current src/routes/+page.svelte file with the above code, update thefirebaseConfig settings in +page.server.js with parameters from your own project), and start your dev server as before, the page should initialise with the single "Product Number 1" record you created in the products collection earlier. Adding new Products should also work exactly as before.

But there's a snag. When you restart the webapp you'll see that you're back to square one with a single "Product Number 1" record. Can you see the problem? Yes, the webapp is still updating the in-core list of products (now located in the new data.products variable). You need to find some way of replacing this with code that updates the products database. Onward and upward!

3.6 How can I get a Svelte `+page.svelte` file to add data to a Firestore database?

What you need is another piece of Firestore API boilerplate code - this time a sequence that creates a new {productNumber: newProductNumber} document in a Firestore products collection (to simplify things, I'm ditching the productDetails property for now). Here it is:

const productsDocData = {productNumber: newProductNumber}
const productsCollRef = collection(db, "products");
const productsDocRef = doc(productsCollRef );
await setDoc(productsDocRef, productsDocData );

Where should this code be located? Currently, the code fired by the "Add Another Product" <form>'s on:click button lives in your +page.svelte file. But Svelte advises that, for security and efficiency reasons, the database update should be performed "server-side" in +page.server.js in an actions() function paralleling the load() function you've already created here. The function is triggered by "posting" data from the <form>.

Here's what the new <form> arrangement in +page.svelte should look like:

// src/routes/+page.svelte - fragment

<script>
    let popupVisible = false;
    export let form;
</script>
<form
    method="POST"
    style="border:1px solid black; height: 6rem; width: 30rem; margin: auto;">
    <p>Products Registration Form</p>
    <label>
        Product Number
        <input name="newProductNumber" />
    </label>
    <button type="submit">Register</button>
</form>

The most important thing here is the presence of the method=POST qualifier on the <form> specification. When the form is submitted, this makes SvelteKit think "ah, I now need to pass the data collected by this form to actions() in a +page.server.js file associated with this page". Because no explicit "action" is requested above, SvelteKit goes looking for a "default" actions() function. Here is is

// src/routes/+page.server.js - fragment
export const actions = {
  default: async (event) => {

    const formData = await event.request.formData();
    // retrieve the newProductNumber string from the form and convert it to a number
    const productNumberAsText = formData.get('newProductNumber');
    const newProductNumber = parseInt(productNumberAsText, 10);

    const productsDocData = { productNumber: newProductNumber };
    const productsCollRef = collection(db, "products");
    const productsDocRef = doc(productsCollRef);
    await setDoc(productsDocRef, productsDocData);

    return ({updateSucceeded: true})

  }
};

The object returned by the "actions" function becomes available to the +page.svelte file through the form prop declared in its <script> section. Here, an export let form; statement parallels the earlier use of a data prop to return the results of a load() function.

Here are the complete versions of +page.svelte and +page.server.js:

// routes/+page.svelte - remove before running
<script>
let popupVisible = false;
export let data; 
//The "data" State variable will be initialised by +page.server.js as an array of {productNumber : value}
// objects
export let form;

</script>

<div style="text-align: center">
<h1>Products Maintenance Page</h1>

{#if !popupVisible}
    <!-- the start position - popup not visible-->

    <p>Currently-registered product numbers:</p>
    {#each data.products as product}
        <!-- display the current list of products-->
        <p style="margin: 0">{product.productNumber}</p>
    {/each}
    <button
        style="display: inline; margin-top: 1rem"
        on:click={() => {
            popupVisible = true;
        }}
        >Add Another Product
    </button>
{:else}

    <!-- display the product registration form-->
    <form  method="POST"
        style="border:1px solid black; height: 6rem; width: 30rem; margin: auto;"
    >
        <p>Product Registration Form</p>
        <label>
            Product Number
            <input 
            name="newProductNumber" type="text"/>
        </label>
        <button type="submit">Register</button>
    </form>
{/if}

</div>

// routes/+page.server.js
import { collection, query, getDocs, orderBy, doc, setDoc } from "firebase/firestore";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

const firebaseConfig = {
  apiKey: "AIzaSyDOVyss .... LsT6n-tWh0GZoPQhM",
  authDomain: "svelte-dev-80286.firebaseapp.com",
  projectId: "svelte-dev-80286",
  storageBucket: "svelte-dev-80286.appspot.com",
  messagingSenderId: "5855 ...  06025",
  appId: "1:585552006025:web:e41 .....  fcc161e6f58"
};

const firebaseApp = initializeApp(firebaseConfig);
const db = getFirestore(firebaseApp);

export async function load() {

  const productsCollRef = collection(db, "products");
  const productsQuery = query(productsCollRef, orderBy("productNumber", "asc"));
  // Because the productNumber field in the products collection is numeric rather than string, orderBy
  // produces numeric sorted order.  If the field were a string, the order would be "lexicographic" which
  // means "12" sorts before "3". It's a nuisance, however, since later we will be inputting productNumber as
  // a string in order to demonstrate validation t in productNumberIsNumeric and also using it
  // to demonstrate dynamic routes, which also demand the use of strings. The .toString and parseInt
  // javascript functions are used to perform conversions where required.
  const productsSnapshot = await getDocs(productsQuery);

  let currentProducts = [];

  productsSnapshot.forEach((product) => {
    currentProducts.push({ productNumber: product.data().productNumber });
  });

  return { products: currentProducts }
}

export const actions = {
  default: async (event) => {

    const formData = await event.request.formData();
    // retrieve the newProductNumber string from the form and convert it to a number
    const productNumberAsText = formData.get('newProductNumber');
    const newProductNumber = parseInt(productNumberAsText, 10)

    const productsDocData = { productNumber: newProductNumber }
    const productsCollRef = collection(db, "products");
    const productsDocRef = doc(productsCollRef);
    await setDoc(productsDocRef, productsDocData);

    return ({updateSucceeded: true})

  }
};

If you copy this code, remember to reset the firestoreConfig data again. If you have problems getting it to work, remember also the advice in the previous post about debugging client-side code and look at the "Postscript sections" below for advice about fixing server-side problems. Good luck!

Note that the FireStore API imports and db configuration statements in +page.server.js have been given "file scope" by moving them out of the functions they serve and relocating them at the top of the file's <script> section. In a more complex project, it would be common practice to configure db in a separate lib folder to enable it to be shared more widely as an import.

You'll also note that the new code drops the resetting of the popupVisible field that previously appeared in the old +page.svelte file's on:click function. Svelte's default action on form submission is to reload the page. Consequently, when the form has been processed, popupVisible is re-initialised as false, the "Currently-registered products:" array is refreshed from the updated Firestore products collection and the popup disappears. As a bonus, the new Product Number will be inserted in the correct sorted order, courtesy of the orderBy("productNumber", "asc") qualifier in the products getDocs.

For cases where your page contains multiple forms, you'll want to be able to specify multiple actions() functions. See Named Actions in Svelte Docs for how to do this.

Caveat: code like this will only work while your Firestore database is public. When you add rules to restrict a collection's access to authorised users (ie users who have "logged in"), the Firestore templates you've been using here will fail. Posts in the next section of this series will explain why and Post 3.4 in particular will explain how you can fall back to code based purely on client-side +page.svelte files. However, since this will be at the expense of security and performance, I hope you'll fight your way through these "minor irritations" and continue developing client-server code. For the present, make sure that your database rules look something like:

    match /products/{document=**} {
      // Allow both read and write access
      allow read, write: if true;
    }

4. Summary

I imagine that this post will have strained your patience to the limit. If you've reached this point with a working webapp and your sanity still intact, give yourself a gold star - you've covered most of the core Svelte topics and got a handle on the essential skills!

That said, there's still a lot to learn. For example, this post has ducked out of describing basic error handling, and form validation arrangements. Beyond that, I also want to introduce you to Svelte routes(ie pages), layouts (page headers and trailers), components, and the tricky issues surrounding security (login design and database rules). Finally, there's the interesting question of how you deploy your webapp for live operation on the web. I hope you'll read on!

Postcript: When things go wrong

The introduction of "server-side" processing in your webapp has fast-tracked you straight into the senior developer league. This is because the "Chrome Inspector" techniques that I hope you've enjoyed using on your +page.svelte files don't work on +page.server.js files. But all is not lost. Here's an introduction to the techniques that a senior developer would use:

Postscript (a): Debugging Server side code in the Terminal Session

Although the VSCode editor will do its best to help you produce sound code, some basic errors will only become apparent when the SvelteKit server tries to run your webapp. At this point, your screen may display a "500 - Internal Error" message (if it displays anything at all!). The browser can't help you much here because a +page.server.js file is essentially invisible here. While the Source tab's Page/localhost storage hierarchy continues to show your +page.svelte file, it has nothing to say about +page.server.js.

But the Inspector knows that an error has occurred and can sometimes give you useful a clue as to its cause. The right-hand end of the menu bar will show a red icon with a cross in the middle. Click the console tab and see what it has to say, but don't expect full details of the problem. wf you need full details, you'll find these in the terminal session where you launched the server with npm run dev.

The problem here is that you'll likely feel the level of detail is probably rather too full. Every error is reported with a "call stack" that details the full sequence of server function calls that preceded the failure point. Here's a short one precipitated by an incorrect field name declaration (I deliberately mistyped const db= as const dba =

ReferenceError: db is not defined
    at load (C:\Users\mjoyc\Desktop\GitProjects\svelte-test\src\routes\+page.server.js:18:38)
    at Module.load_server_data (C:\Users\mjoyc\Desktop\GitProjects\svelte-test\node_modules\@sveltejs\kit\src\runtime\server\page\load_data.js:61:41)
    at C:\Users\mjoyc\Desktop\GitProjects\svelte-test\node_modules\@sveltejs\kit\src\runtime\server\page\index.js:140:19

A terminal window isn't a good place to view information like this. Sometimes you have to scroll up or down to find what you want, and information may be additionally obscured by output from other activities. Nevertheless, it's all you've got, so you need to make the best of it. Personally, when dealing with something particularly tricky, I have found it often helps to "clear the ground" by killing the terminal session, restarting with npm run dev and re-running the problem code. This gives you a clean statement of any error messages and ensures the problem isn't just down to internal server issues.

However, in the example shown above, the cause of the error is signalled very clearly - the server has encountered a reference to a db variable in +page.server.js at line 18 column 38 and db hasn't been declared. In this case, the terminal session has given you everything you need to know, I think.

The terminal window can help you fix problems with your logic, too. In the past, "debugging" was usually carried out by placing console.log messages at strategic points in the code, and it's easy enough to use this approach here. A typical log message would be:

console.log("Arrived at X with a= " + a);

A log message like this placed in a +page.server.js file will be displayed in the VSCode terminal window (by contrast, log statements in a client-side +page.svelte code will continue to be displayed in the browser's console window).

The arguments to the console.log() statement can be configured in many different ways. These are designed variously to assist with the labelling of the statement (i.e. tying a message to its source) and the formatting of its content. You might find it helpful to ask ChatGPT for a tutorial on the subject. A variant I find really useful takes the form "console.log({x})", where "x" can be any variable, regardless of variable type. When "x" is an object, for example, this will produce terminal session output of the form "{x: { ... object content ...}}"

Postscript (b): Debugging Server-side code in the VSCode debugger

Console.log messages are fine for fixing minor issues, but by now you expect to be able to use something with the sophistication of the browser "breakpoint" debugging tool. Fear not. You can now find this in the VSCode. editor. Here's what you do:

Open the +page.server.js file you want to debug and set a breakpoint at a point you'd like to inspect. You do this by mousing over the source line you want to use as a breakpoint and clicking on the pale red dot that will appear at its left-hand side. The pale red dot now changes to bright red.
In the VSCode command palette (shortcut "ctrl shift p") choose Debug: Attach to node process and get a list of projects in your workspace. Select the one you want to debug.
Note that the terminal session that you've just launched is labelled as "Javascript Debug Terminal". Type 'npm run dev` into this terminal and note how the usual Vite output that appears includes an additional "Debugger attached" line. Note also how VSCode's activity bar has turned orange
Now mouse over the http://localhost address displayed by Vite and launch the webapp with a "ctrl-click". Your webapp now opens in a popup window.
You'll now find that the editor page for your +page.server.js file has become an active debugging session with execution halted on the first breakpoint. A panel at the top of the editor window displays the familiar "advance to next breakpoint" etc buttons, and mousing over field names will reveal tooltips that display their values. As before, if a debug session is halted on a variable assignment statement, you'll only see the result of this when you advance to the next statement.
Terminate the debug session by mousing over the icon at the far end of the debug controls panel. This toggles between "disconnect" and "stop" actions when you press the "alt" key. Click this when it displays "disconnect" and the orange VSCode activity bar will turn blue again. If you want to resume debugging, "ctrl click" on the webapp URL in the debugging terminal window again (which will stay active until you explicitly "bin" it)

The screenshot below shows the +page.server.js file for this post halted on the return from the load() function. A "mouseover" on the products property for the return at this point displays the result of reading the Firestore products collection.

For full details of the facilities available in the VSCode debugger, see the documentation at VSCode debugging

NgSysV2-3.4: A Serious Svelte InfoSys: Rules-friendly version

MartinJ — Mon, 25 Nov 2024 21:45:28 +0000

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 series has previously described how you can use the Svelte framework in conjunction with Google's Firestore database Client API to develop useful information systems quickly and enjoyably. Sadly, however, Post 3.3 revealed how Firebase's otherwise excellent authentication system doesn't support Firestore activity in server-side load() and actions() functions where database rules reference the auth object.

Skipping your Firestore authorisation rules isn't an option - without these, your database is wide open to anyone who can hijack the firebaseConfig keys from your webapp. This post describes ways to re-work the Svelte server-side code so that it runs on the client side while Firestore rules remain firmly in place.

2. Reworking 'compromised' `load()` functions

Not all load() functions will be affected by the presence of Firestore rules. Those that reference Firestore public collections will still run happily server-side. The Client API is still available in +page.server.js files - it just won't work if it's asked to use collections protected by auth.

If your load() function addresses public files and you simply want to avoid server-side debugging, you might consider moving your load() function into a +page.js file. This works exactly like a +page.server.js file - Svelte will still run the function automatically at load time. But this happens client-side now where it can be debugged in the browser. See Svelte docs at Loading data for details

However, a 'compromised' load() function (typically where Firestore rules are used to ensure that users can only access their own data) must be relocated into client-side code. Typically, this would be reworked as a new, appropriately named, function in the <script> section of its associated +page.svelte file.

But now you must find a way to launch your relocated load() function automatically on page initialisation - you no longer benefit from Svelte's built-in arrangements for native load() functions. The problem is that your re-located function is asynchronous and so can't be launched directly from a +page.svelte file's <script> section. This problem is solved by using Svelte's onMount utility.

"OnMount" is a Svelte lifecycle "hook" that runs automatically when a webapp page is launched. Inside an onMount() you can now safely await your relocated load() function - you may recall that you met it earlier in the logout function. You can find a description at Svelte Lifecycle Hooks.

3. Reworking 'compromised' `actions()` functions

In this case, there are no options. Compromised actions() functions must be relocated into the <script> section of the parent +page.svelte file. Form submit buttons here must be reworked to "fire" the action via on:click arrangements referencing the relocated function.

4. Example: Rules-friendly versions of the `products-display` page

In the following code examples, a new products-display-rf route displays the old "Magical Products" list of productNumbers. The load() used here isn't compromised but its code is still moved to a +page.js file to let you confirm that you can debug it in the browser. The only other changes are:

the code now includes the extensions to display the productDetails field when a product entry in the "Magical Products" list is clicked.
firebase-config is now imported from the lib file introduced in the last post

// src/routes/products-display-rf/+page.svelte
<script>
    export let data;
</script>

<div style="text-align: center">
    <h3>Current Product Numbers</h3>

    {#each data.products as product}
        <!-- display each anchor on a separate line-->
         <div  style = "margin-top: .35rem;">
        <a href="/products-display-rf/{product.productNumber}"
            >View Detail for Product {product.productNumber}</a
        >
    </div>
    {/each}
</div>

// src/routes/products-display-rf/+layout.svelte
<header>
    <h2 style="display:flex; justify-content:space-between">
        <a href="/about">About</a>
        <span>Magical Products Company</span>
        <a href="/inventory_search">Search</a>
    </h2>
</header>

<slot></slot>

<trailer>
    <div style="text-align: center; margin: 3rem; font-weight: bold; ">
        <span>© 2024 Magical Products Company</span>
    </div>
</trailer>

// routes/products-display-rf/+page.js
import { collection, query, getDocs, orderBy } from "firebase/firestore";
import { db } from "$lib/utilities/firebase-client"

export async function load() {

  const productsCollRef = collection(db, "products");
  const productsQuery = query(productsCollRef, orderBy("productNumber", "asc"));
  const productsSnapshot = await getDocs(productsQuery);

  let currentProducts = [];

  productsSnapshot.forEach((product) => {
    currentProducts.push({ productNumber: product.data().productNumber });
  });

  return { products: currentProducts }
}

// src/routes/products-display-rf/[productNumber]/+page.svelte
<script>
  import { goto } from "$app/navigation";
  export let data;
</script>

<div style="text-align: center;">
  <span
    >Here's the Product Details for Product {data.productNumber} : {data.productDetails}</span
  >
</div>
<div style="text-align: center;">
  <button
    style="display: inline-block; margin-top: 1rem"
    on:click={() => {
      goto("/products-display-rf");
    }}
  >
    Return</button
  >
</div>

// src/routes/products-display-rf/[productNumber]/+page.js
import { collection, query, getDocs, where } from "firebase/firestore";
import { db } from "$lib/utilities/firebase-client";

export async function load(event) {
  const productNumber = parseInt(event.params.productNumber, 10);

  // Now that we have the product number, we can fetch the product details from the database

  const productsCollRef = collection(db, "products");
  const productsQuery = query(productsCollRef, where("productNumber", "==", productNumber));
  const productsSnapshot = await getDocs(productsQuery);
  const productDetails = productsSnapshot.docs[0].data().productDetails;

  return {
    productNumber: productNumber, productDetails: productDetails
  };
}

Copy this code into new files in "-rf" suffixed folders. But do take care as you're doing this - working with lots of confusing +page files in VSCode's cramped folder hierarchies requires close concentration. When you're done, run your dev server and test the new page at the http://localhost:5173/products-display-rf address.

The "Products Display" page should look exactly the same as before but, when you click through, the "Product Details" page should now display dynamically-generated content.

5. Example: Rules-friendly version of the `products-maintenance` page

Things are rather more interesting in a client-side version of the products-maintenance page.

Because your Firebase rule for the products collection now reference auth (and thus requires prospective users to be "logged-in"), the actions() function that adds a new product document is compromised. So this has to be moved out of its +page.server.js file and relocated into the parent +page.svelte file.

Here, the function is renamed as handleSubmit() and is "fired" by an on:submit={handleSubmit} clause on the <form> that collects the product data.

Although the products-maintenance page doesn't have a load() function, onMount still features in the updated +pagesvelte file. This is because onMount provides a useful way of usefully redirecting users who try to run the maintenance page before they've logged-in.

See if you can follow the logic listed below in a new products-maintenance-rf/+page.svelte file and an updated /login/+page.svelte file.

// src/routes/products-maintenance-rf/+page.svelte
<script>
    import { onMount } from "svelte";
    import { collection, doc, setDoc } from "firebase/firestore";
    import { db } from "$lib/utilities/firebase-client";
    import { goto } from "$app/navigation";
    import { auth } from "$lib/utilities/firebase-client";
    import { productNumberIsNumeric } from "$lib/utilities/productNumberIsNumeric";

    let productNumber = '';
    let productDetails = '';
    let formSubmitted = false;
    let databaseUpdateSuccess = null;
    let databaseError = null;

    let productNumberClass = "productNumber";
    let submitButtonClass = "submitButton";

    onMount(() => {
        if (!auth.currentUser) {
            goto("/login?redirect=/products-maintenance-rf");
            return;
        }
    });

    async function handleSubmit(event) {
        event.preventDefault(); // Prevent default form submission behavior
        formSubmitted = false; // Reset formSubmitted at the beginning of each submission

        // Convert productNumber to an integer
        const newProductNumber = parseInt(productNumber, 10);
        const productsDocData = {
            productNumber: newProductNumber,
            productDetails: productDetails,
        };

        try {
            const productsCollRef = collection(db, "products");
            const productsDocRef = doc(productsCollRef);
            await setDoc(productsDocRef, productsDocData);

            databaseUpdateSuccess = true;
            formSubmitted = true; // Set formSubmitted only after successful operation

            // Clear form fields after successful submission
            productNumber = '';
            productDetails = '';
        } catch (error) {
            databaseUpdateSuccess = false;
            databaseError = error.message;
            formSubmitted = true; // Ensure formSubmitted is set after error
        }
    }
</script>

<form on:submit={handleSubmit}>
    <label>
        Product Number
        <input
            bind:value={productNumber}
            name="productNumber"
            class={productNumberClass}
            on:input={() => {
                formSubmitted = false;
                if (productNumberIsNumeric(productNumber)) {
                    submitButtonClass = "submitButton validForm";
                    productNumberClass = "productNumber";
                } else {
                    submitButtonClass = "submitButton error";
                    productNumberClass = "productNumber error";
                }
            }}
        />
    </label>
    &nbsp;&nbsp;

    <label>
        Product Details
        <input
            bind:value={productDetails}
            name="productDetails"
            class={productNumberClass}
        />
    </label>
    &nbsp;&nbsp;

    {#if productNumberClass === "productNumber error"}
        <span class="error">Invalid input. Please enter a number.</span>
    {/if}

    <button class={submitButtonClass} type="submit">Submit</button>
</form>

{#if formSubmitted}
    {#if databaseUpdateSuccess}
        <p>Form submitted successfully.</p>
    {:else}
        <p>Form submission failed! Error: {databaseError}</p>
    {/if}
{/if}

<style>
    .productNumber {
        border: 1px solid black;
        height: 1rem;
        width: 5rem;
        margin: auto;
    }

    .submitButton {
        display: inline-block;
        margin-top: 1rem;
    }

    .error {
        color: red;
    }

    .validForm {
        background: palegreen;
    }
</style>

// src/routes/login/+page.svelte
<script>
    import { onMount } from "svelte";
    import { goto } from "$app/navigation"; // SvelteKit's navigation for redirection
    import { auth } from "$lib/utilities/firebase-client";
    import { signInWithEmailAndPassword } from "firebase/auth";

    let redirect;
    let email = "";
    let password = "";

    onMount(() => {
        // Parse the redirectTo parameter from the current URL
        const urlParams = new URLSearchParams(window.location.search);
        redirect = urlParams.get("redirect") || "/";
    });

    async function loginWithMail() {
        try {
            const result = await signInWithEmailAndPassword(
                auth,
                email,
                password,
            );
            goto(redirect);
        } catch (error) {
            window.alert("login with Mail failed" + error);
        }
    }
</script>

<div class="login-form">
    <h1>Login</h1>
    <form on:submit={loginWithMail}>
        <input bind:value={email} type="text" placeholder="Email" />
        <input bind:value={password} type="password" placeholder="Password" />
        <button type="submit">Login</button>
    </form>
</div>

<style>
    .login-form {
        display: flex;
        flex-direction: column;
        align-items: center;
        justify-content: center;
        gap: 20px;
        height: 100vh;
    }

    form {
        width: 300px;
        margin: 0 auto;
        padding: 20px;
        border: 1px solid #ccc;
        border-radius: 5px;
        background-color: #f5f5f5;
        box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
    }

    input[type="text"],
    input[type="password"] {
        width: 100%;
        padding: 10px 0;
        margin-bottom: 10px;
        border: 1px solid #ccc;
        border-radius: 3px;
    }

    button {
        display: block;
        width: 100%;
        padding: 10px;
        background-color: #007bff;
        color: #fff;
        border: none;
        border-radius: 3px;
        cursor: pointer;
    }

    div button {
        display: block;
        width: 300px;
        padding: 10px;
        background-color: #4285f4;
        color: #fff;
        border: none;
        border-radius: 3px;
        cursor: pointer;
    }
</style>

Test this by starting your dev server and launching the /products-maintenance-rf page. Because you're not logged you'll be redirected immediately to the login page. Note that the URL displayed here includes the products-maintenance-rf return address as a parameter.

Once you're logged in, the login page should send you back to products-maintenance-rf. Since you're now logged in, the new version of the product input form (which now includes a product detail field) will be displayed.

The input form works very much as before, but note how it is cleared after a successful submission, enabling you to enter further products. Use your products-display-rf page to confirm that new products and associated product details data are being added correctly.

Note also, that when a user is logged in, you can use the auth object thus created to obtain user details such as email address:

const userEmail = auth.currentUser.email;

Check with chatGPT to find out what else is available from auth. For example, you might use the user's uid to display only documents 'owned' by that user.

6. Summary

If you have simple objectives, the "Rules-friendly" approach described here, for all its deficiencies, may be perfectly adequate for your needs. Client-side Svelte provides a wonderful playground to develop personal applications quickly and painlessly. But be aware of what you've lost:

efficient data loading - there is likely to be a delay before data appears on the screen.
secure input validation
assured SEO

So, if you have your sights set on a career as a serious software developer, please read on. But be warned, things get rather more "interesting"!