Forem: Aditya Naag

How to Build the Snake Game Using Lightning Web Components

Aditya Naag — Tue, 15 Sep 2020 16:30:15 +0000

In this blog post, we’ll explore how we can build the classic Snake game using Lightning Web Components Open Source (LWC OSS). We’ll also explore how we can optimize the performance of the game and deploy it to any platform of our choice.

The below image shows how the completed game looks.

Check out the source code here
Play the game on Heroku or GitHub pages. You can also install it on your desktop and play offline.
Check out the recording here to see how we built this game live from scratch.

The Guiding Principle

The guiding principle when building this game is the fact that “Using JavaScript to manipulate the DOM isn’t recommended because the Lightning Web Components engine does it more efficiently”.

We also won’t use the HTML5 Canvas because the only way to modify the contents of a canvas is using the Canvas API which is unrelated to Lightning Web Components and doesn’t leverage its benefits.

With this in mind, let’s dive in. We’ll start by creating the game area, to which we’ll add the snake and the food. We’ll then add the logic to move the snake based on keyboard controls and make the snake longer every time it eats the food. Finally, we’ll deploy the game to GitHub Pages and Heroku.

Creating the game area

At the heart of the game is the area on which the snake moves. Since we aren’t going to use the HTML5 Canvas, the trick is to divide the available space into blocks of equal size, where each block is a div element.

To calculate the number of blocks needed to cover the area, we divide the available area by the block size. To get the available area we can use the clientWidth and clientHeight properties of the HTMLElement.

const gameContainerEl = this.template.querySelector('.game-container');
const eWidth = gameContainerEl.clientWidth;
const eHeight = gameContainerEl.clientHeight;

Once we’ve identified the number of blocks needed to cover the area, the next step is to actually create the blocks.

One approach is to create a div element for each block using JavaScript and explicitly adding it to the DOM. But as per our guiding principle, using the LWC engine to manipulate DOM is more efficient than using JavaScript.

To let the LWC Engine create the DOM for us, we can create an array of objects, where each object represents a block. We can then iterate over these objects in the template using the for:each directive to render the blocks. Each block is given an ID which we can use throughout the game to find that block. This ID is made up of the X and Y coordinates of the block in the form of X:Y.

This way, the LWC engine creates the required DOM nodes based on the number of elements in the array. Also, key attribute is used by the LWC engine to optimize performance by only re-rendering the item that changed in the list.

@track gameBlocks = [];
renderedCallback(){ 
    for (let y = 0; y < this.yMax; y++) { 
        for (let x = 0; x < this.xMax; x++) { 
            ... 
            obj = { id: `${x}:${y}` }; 
            ... 
            this.gameBlocks.push(obj); 
        } 
    }
}

<template for:each={gameBlocks} for:item="block"> 
      <div key={block.id}> ... </div>
</template>

This presents an interesting problem. If we use @track on a property, then changing it in the renderedCallback() will create an infinite loop of rendering cycles. To fix this, we can add a limiter using a boolean variable. But that doesn’t solve the problem completely.

Every time we push a new element to the array inside a for-loop, a rerender is triggered, which impacts the performance. To overcome this problem, we can create a temporary array that holds all the elements until the for-loop is complete. We can then simply assign its final value to the main array.

@track gameBlocks = []; 
gameRendered= false;

renderedCallback(){ 
    if(!this.gameRendered){ 
        const tmpBlocks = []; //Declaring a temporary array 
        for (let y = 0; y < this.yMax; y++) { 
            for (let x = 0; x < this.xMax; x++) { 
                obj = { id: `${x}:${y}`}; } 
                tmpBlocks.push(obj); 
            }
        } 
        this.gameRendered = true; //assigning the temporary array to the main one 
        this.gameBlocks = tmpBlocks; 
    }
}

Creating the snake and food

The next step is to show the snake and food in the game area. One of the ways we can do this is to use CSS classes to color the div blocks where the snake and food are to be shown. We can then keep adding and removing these CSS classes to each block to create the effect of the snake moving.

We can add new properties to the block objects to denote if a block is the snake, food, or is empty.

...
obj = { id: `${x}:${y}`, snake: true, food: false };
...

In the template, we can use the if:true directive to decide which type of block we want to show.

<template for:each={gameBlocks} for:item="block"> 
    <template if:true={block.snake}> 
        <div class="snake" key={block.id}></div> 
    </template> 
    <template if:true={block.food}> 
        <div class="food" key={block.id}></div> 
    </template> 
    ...
</template>

This approach works but causes slight performance degradation. This is because each time the snake moves, the if:true template tags have to be evaluated and the corresponding DOM nodes have to be created/destroyed which is an expensive operation.

A better approach is to manipulate the class on the existing DOM node as it is less expensive than destroying and recreating a DOM node. To do this, we can create another property called class on the block object, and assign its value to the class attribute of the div element.

This simple update of an element’s attribute value results in better performance as there are fewer evaluations.

...
obj = { id: `${x}:${y}`, snake: true, food: false, class: 'snake' };
...

<template for:each={gameBlocks} for:item="block"> 
    <div class={block.class} key={block.id}></div>
</template>

Now moving on to creating the food. Since food is placed randomly on the game area, we can use the Math.random() function to randomly decide the div block where the food must be present.

const xFood = Math.floor(Math.random() * (this.xMax - 1));
const yFood = Math.floor(Math.random() * (this.yMax - 1));
const foodPosIndex = this.gameBlocks.findIndex( (x) => x.id === `${xFood}:${yFood}`);
this.gameBlocks[foodPosIndex].food = true;
this.gameBlocks[foodPosIndex].class = 'food';

Moving the snake and making it longer

The snake can be moved across the game area by incrementing the position of the head of the snake based on the direction it’s moving. For example, if the snake is moving right, then the X value of the head is incremented by 1, and Y value stays 0.

xSpeed = 1;
ySpeed = 0; 
xHead = 0;
yHead = 0; 

move() { 
    this.xHead += this.xSpeed; 
    this.yHead += this.ySpeed;
}

To change the direction of the snake, we just need to update the xSpeed and ySpeed properties based on what arrow key is pressed.

window.addEventListener('keydown', (e) => { 
    e.preventDefault(); 
    switch (e.key) { 
        case 'ArrowUp': 
            this.xSpeed = 0; 
            this.ySpeed = -1; 
            break; 
        case 'ArrowDown': 
        ... 
    }
});

Finally, the move() function can be called at regular intervals depending on how fast we want the snake to move. We can call this whenever we want to start the game. For example, on click of a “Start” button, on page load, and so on.

setInterval(() => { 
    this.move(); 
}, 300);

The trickiest part of creating the game is to increase the length of the snake’s tail whenever it eats the food. To achieve this, we’ll need to store the block IDs of the tail in a new array. To move the tail along with the head, we’ll need to remove the first element of the tail array and add the current position of the head to the end of the tail array. Whenever the snake eats the food, we just don’t remove the first element of the array.

move() { 

    // Moving the tail. 
    // Removing the first element only if food hasnt been eaten in the previous step 
    const lastElement = this.tail[this.tail.length - 1]; 
    if (lastElement !== `${this.xHead}:${this.yHead}`) { 
        this.tail.push(`${this.xHead}:${this.yHead}`); 
        const removedElement = this.tail.shift(); 
        const curPosIndex = this.gameBlocks.findIndex( (x) => x.id === removedElement ); 
        this.gameBlocks[curPosIndex].snake = false; 
    } 

    // Adding the current head to the tail if food is eaten 
    // so that in the next step we can determine if the snake ate food in the previous step 
    if (this.gameBlocks[newPosIndex].food) { 
        this.score++; 
        this.tail.push(`${this.xHead}:${this.yHead}`); 
        ... 
    }
}

Deploying to multiple platforms

The app type that we choose when creating the LWC OSS project determines the platforms on which the app can be deployed. We can choose Standard or PWA to create a Web app or choose Electron App to create a Desktop app. We chose PWA when building this game so that it can run on the browser, and can be installed on our desktop to be run offline.

The LWC OSS project also includes the tools and services we need to build, test, and run our project locally. Each of these tools and services can be configured based on our needs using the corresponding config files.

The lwc-services.config.json file lets us configure settings like the directory for the build output, port numbers for development and production servers, as well as many more.

The scripts property in the package.json file lists all the scripts we can run on the project. For example, The build script builds the project and creates the executable files in the configured build directory. These executable files can then be deployed to any platform of our choice.
The watch script runs the project locally in “development” mode, meaning that any changes to the source files will auto-refresh the browser. The serve script on the other hand runs the project in “production” mode, where the executable files are served from the build directory.

With this in mind, let's look at how we can deploy the game to GitHub pages and Heroku. There are many ways to do this, and we picked the easiest one which involves pushing the code to GitHub and triggering the deployments to both environments from there.

GitHub Pages

GitHub Pages needs the executable files to be present either in the docs folder or the gh-pages branch.

Let's take the docs folder approach. This means that the build output of the project must go into the docs folder. To do this, we’ll need to update the lwc-services.config.json to configure the build directory (buildDir) to be docs. This is how the updated file looks:

module.exports = { 
    buildDir: './docs', 
    resources: [
        { from: 'src/resources/', to: 'docs/resources/' }
    ]
};

Once this is done, we'll need to run the command npm run build using Command Line or Terminal, to create the docs folder with the required executable files. We can then push this folder to GitHub and enable GitHub Pages from the Settings menu as shown below.

This auto triggers a deployment to GitHub Pages. Alternately, we can also create GitHub actions to automatically run the build command and update the docs folder or gh-pages branch whenever code is pushed to the repo.

Heroku

To deploy the same code to Heroku, we’ll need to create a file with the name Procfile in the root of the project, with the below contents.

web: npm run serve

The serve script from package.json spins up an Express server to serve the static HTML content from the build directory. Since we configured the build directory to be docs in the previous step, we also need to update the scripts/server.js file to reflect the same.

...
const DIST_DIR = './docs';
...

These changes can then be committed to the GitHub Repo.

We can then create a new app on Heroku, select GitHub as the Deployment Method, choose your GitHub repo, and enable Automatic Deploys. Learn more about using GitHub as a deployment method here.

This way, once we push code to GitHub, it automatically deploys to both GitHub pages and Heroku.

Summary

Building a game is a great and fun way to dive deep into Lightning Web Components. As we have seen, there can be multiple ways to achieve the desired result, but not every way leads to optimal performance. Also, since the apps we build with Lightning Web Components are truly reusable across different platforms, there is no better time than now to start thinking of scaling your solutions beyond just a single platform.

Hopefully, this has sparked your imagination and inspired you to build other games. Hint: Other classic games like Tetris, Ludo, and many more. We can’t wait to see what you build.

Source Code

Don’t forget to check out the source code of this game. Feel free to fork it, raise issues, or submit a PR to improve the game.

Accessing Salesforce from apps built with Lightning Web Components Open Source

Aditya Naag — Wed, 17 Jun 2020 00:14:29 +0000

Lightning Web Components (LWC) is Salesforce’s Open Source (OSS) UI framework that leverages the web standards breakthroughs of the last 5 years. You can use it to build enterprise-scale apps with your favorite tools like Webpack, TypeScript, and Babel, and run them on Heroku, Google Cloud Platform, Salesforce or anywhere else.

When running these apps on different platforms, you can choose your own backend stack and data source, or you may want surface data from Salesforce in them. In this post, we will explore some options and considerations when using Salesforce as the data source. You’ll find code snippets and links to relevant resources through out this post. You can also refer to this sample code for a fully functional example.

Authentication

Salesforce provides a comprehensive set of REST and SOAP APIs that can be used to access its data and services from a client or server. The first step before accessing the APIs, is to establish a session with Salesforce. You can either use a username and password, or any of the OAuth 2.0 flows listed here. Depending on your use case, these flows can be executed by client-side or server-side JavaScript. You can either build this logic from scratch or use external libraries like JSforce. Here are some considerations when deciding on an authentication flow for your app.

Client Side Authentication

You can use the OAuth 2.0 User-Agent Flow to execute the handshake process using client side JavaScript alone. It involves a simple redirection to the /oauth2/authorize endpoint and takes in the Consumer Key of a Connected App as a parameter. Once the authorization is successful, the access token is encoded in the redirection URL.

Here is a sample code snippet to redirect users to the Salesforce endpoint:

<a href="https://login.salesforce.com/services/oauth2/authorize?response_type=token&
                client_id=<INSERT_CLIENT_ID_HERE>&
                redirect_uri=<INSERT_REDIRECT_URI_HERE>">Login to Salesforce</a>

When you run client-side JavaScript, all the code is executed on the user's device, so sensitive data like passwords and client secrets are accessible and exploitable. For this reason, this flow doesn’t use the client secret. However, the access token is encoded into the redirection URL which is exposed to the user and other apps on the device. Hence, care must be taken to remove callbacks from browser history. You can call window.location.replace() to remove the callback from the browser’s history. It is best to use this type of Auth flow when building Lightning Web Components for desktop or mobile apps that have an embedded browser.

Once you have the access token, you can pass it in the header of any HTTP requests to access Salesforce APIs. Building and sending a request from client-side JavaScript poses a risk, because the access token becomes available to the client and can be exploited. Therefore, sensitive business logic involving access tokens, usernames and passwords must never be written in client side JavaScript, because they can be inadvertently exposed.

To increase security and provide a better level of abstraction between your custom application and the APIs, you should use a middleware like Express, MuleSoft or any other ESB of your choice.

Server Side Authentication

You can use the Web server flow or the JWT Bearer flow to execute the handshake process using server side JavaScript like Node.js or any other stack of your choice. When creating an LWC project, the create-lwc-app tool provides an option to create and use an Express server as a backend. You can choose an OAuth flow that suits your requirements. For instance, you can use the JWT Bearer flow when you want to use a single integration user to access data on behalf of all users. Use cases include showing read-only data (e.g. product catalog) to unauthenticated users. The web-server flow on the other hand can be used for individual user authorization. Use cases include websites where data relevant to the logged in user is shown (e.g. history, favorites, preferences etc.). It is also important to note that both the OAuth flows require a Connected App to be configured in Salesforce.

When running authentication flows on a server, it is expected that the server protects and securely stores all the secrets. In the case of Web Server flow, the client secret that prevents a spoofing server must be stored securely. In the case of JWT Bearer flow, an X509 Certificate that corresponds to the private key of the app must be created and stored in a keystore.

These secrets and certificate aliases also have to be configurable (generally using Environment Variables) and should never be hardcoded into your codebase. This also allows you to change them without rebuilding the app and to deploy instances of your app in different environments with ease.

When developing locally, for example with Node.js, these can be stored in a .env file, which can then be accessed in your code by using libraries like dotenv, saving you the trouble of setting them manually every time. You should exclude sensitive configuration files like .env from version control by referencing them in specific ignore files like .gitignore for git.

Here is a code snippet that lets you connect to Salesforce using the Web Server flow. This code leverages Express server as the backend and also uses the JSforce and dotenv libraries mentioned earlier.

// Initialize Express Instance
const app = express();

//Read Environment Variables
const {
    SALESFORCE_LOGIN_DOMAIN,
    SALESFORCE_CLIENT_ID,
    SALESFORCE_CLIENT_SECRET,
    SALESFORCE_CALLBACK_URL
} = process.env;

// Initialize OAuth2 config
const oauth2 = new jsforce.OAuth2({
    loginUrl: SALESFORCE_LOGIN_DOMAIN,
    clientId: SALESFORCE_CLIENT_ID,
    clientSecret: SALESFORCE_CLIENT_SECRET,
    redirectUri: SALESFORCE_CALLBACK_URL
});

// Login to Salesforce
app.get('/oauth2/login', (req, res) => {
    res.redirect(oauth2.getAuthorizationUrl({ scope: 'api' }));
});

// Callback function to get Auth Token
app.get('/oauth2/callback', (req, res) => {
    const conn = new jsforce.Connection({ oauth2 });
    const { code } = req.query;
    conn.authorize(code, (error) => {
        if (error) {
            res.status(500).send(error);
            return;
        }
       //Saving the access token and instance URL in a Node Session for later access  
        req.session.sfdcAccessToken = conn.accessToken;
        req.session.sfdcInstanceUrl = conn.instanceUrl;
    });
});

The listener to the /oauth2/login endpoint redirects a user to the Salesforce endpoint. Once the user logs in, Salesforce redirects them back to the /oauth2/callback endpoint. The listener then retrieves the code parameter from the request, and calls the conn.authorize function to retrieve the access token.

Data Residency

Securing access to Salesforce data doesn’t stop with authentication. Data must be stored and transmitted securely as well. Data on the Salesforce Platform is secured with its core security capabilities like Sharing Model, Object and Field Level Security and optionally Salesforce Shield for encryption and high compliance. Using Salesforce APIs allows real time access to data without copying it. The data returned by the API is bound by the permissions of the user accessing the API.

Depending on your use case, you might want to replicate Salesforce data into a local/managed database. Since you can deploy LWC OSS apps on any platform, there are different options that each platform provides for data storage and replication. For example, Heroku Connect is a Heroku add-on that provides a data synchronization service between Salesforce and Heroku Postgres databases. Add-Ons/Connectors like these are built to securely store tokens, and establish a session with Salesforce when needed. It is important to remember that once data is replicated locally, it is not bound by the same Sharing Model that is present in Salesforce. It is therefore necessary to implement your own access control mechanism.

Never write the logic that queries for data or filters data based on access controls on the client side, because it can be easily tampered with. In the screenshot below, an if condition is being used by the component to only show the data relevant to the logged in user. This statement can be easily removed using browser tools which would then give the logged in user access to all the data that is being returned by the server.

As a best practice, you should always use a middleware to abstract sensitive logic from the client-side and make sure that the middleware returns only the data that’s relevant to the user and nothing more.

Summary

In this post, you’ve learned about different approaches to authenticate to Salesforce from an app built with LWC OSS and what factors determine the approach you take. You’ve seen drawbacks of accessing data from the client side, and how a server can help you secure your implementation. You've also seen how the responsibility of data security varies with choice of data residency. However, it is also important to note that this blog post doesn’t exhaustively list all of the options available for secure Salesforce data access, but instead provides general indication patterns and principles that are used.

Now it's time to get hands-on! Below are a few resources to help you get started.

Also, check out the below content from Trailhead, which is Salesforce’s learning experience platform that contains a library of educational content:

Trailhead Project: Access Salesforce Data with Lightning Web Components Open Source
Trailhead Module: Connected App Basics