TypeScript Tutorial: Creating a Simple Web-Based Interactive Story

Written by

learnmodernjavascript

in

Have you ever wanted to create an interactive story, a choose-your-own-adventure style experience, but felt overwhelmed by the thought of complex coding? This tutorial will guide you through building a simple, yet engaging, web-based interactive story using TypeScript. We’ll break down the concepts into manageable steps, making it accessible for beginners while providing enough depth to keep intermediate developers interested. We’ll explore how to structure the story, handle user choices, and display the results dynamically in the browser. By the end, you’ll have a functional interactive story and a solid understanding of how TypeScript can be used to create interactive web applications.

Why Build an Interactive Story?

Interactive stories are a fantastic way to engage users. They offer a unique level of immersion, allowing readers to shape the narrative and experience the consequences of their decisions. Beyond entertainment, building an interactive story is a great learning experience. It forces you to think about program flow, user input, and state management – all fundamental concepts in software development. This tutorial will teach you practical TypeScript skills while allowing you to unleash your creativity.

What We’ll Cover

In this tutorial, we will cover the following key topics:

  • Setting up a basic TypeScript project.
  • Defining story elements using TypeScript interfaces and classes.
  • Creating a data structure to represent the story’s branching paths.
  • Handling user input and updating the story state.
  • Displaying story content dynamically in the browser using HTML and JavaScript.
  • Adding basic styling with CSS.

Prerequisites

Before we begin, you’ll need a few things:

  • A basic understanding of HTML, CSS, and JavaScript.
  • Node.js and npm (or yarn) installed on your computer.
  • A code editor (like VS Code, Sublime Text, or Atom).

Setting Up Your TypeScript Project

Let’s get started by setting up our project. Open your terminal or command prompt and create a new directory for your project. Navigate into that directory and initialize a new npm project:

mkdir interactive-story
cd interactive-story
npm init -y

Next, install TypeScript as a development dependency:

npm install --save-dev typescript

Now, create a `tsconfig.json` file in your project root. This file configures the TypeScript compiler. You can generate a basic one using the TypeScript compiler itself:

npx tsc --init

You can customize the `tsconfig.json` file as needed, but the default settings are often a good starting point. We’ll make a few small modifications. Open `tsconfig.json` and change the following settings:

{
  "compilerOptions": {
    "target": "es5", // Or "es6", "esnext" depending on your needs
    "module": "commonjs", // Or "esnext", "amd", etc.
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Here’s a breakdown of the key options:

  • target: Specifies the JavaScript version to compile to. es5 is widely supported, but you can use newer versions if your target browsers support them.
  • module: Defines the module system to use (e.g., CommonJS, ESNext).
  • outDir: The directory where the compiled JavaScript files will be placed.
  • rootDir: The root directory of your TypeScript source files.
  • strict: Enables strict type checking. Highly recommended!
  • esModuleInterop: Allows you to import CommonJS modules as ES modules.
  • skipLibCheck: Skips type checking of declaration files (e.g., those in node_modules).
  • forceConsistentCasingInFileNames: Enforces consistent casing in filenames.

Create a `src` directory in your project root. This is where we’ll put our TypeScript code. Inside the `src` directory, create a file named `index.ts`. This will be our main entry point.

Defining Story Elements with TypeScript

Let’s define the core elements of our interactive story using TypeScript. We’ll use interfaces and classes to represent the different components of the story.

Interfaces

Interfaces define the structure of our data. We’ll start with an interface for a story scene:

interface Scene {
  id: string;
  text: string;
  choices?: Choice[]; // Optional choices
}

This `Scene` interface has three properties:

  • id: A unique identifier for the scene (e.g., “start”, “forest”).
  • text: The text content of the scene that the user will read.
  • choices: An optional array of `Choice` objects, representing the user’s options.

Now, let’s define the `Choice` interface:

interface Choice {
  text: string;
  nextSceneId: string;
}

The `Choice` interface has two properties:

  • text: The text of the choice that the user will see.
  • nextSceneId: The `id` of the scene that the choice leads to.

Example Story Data

Let’s define some sample story data. Create a variable to hold our story scenes. This will be an array of `Scene` objects.

const story: Scene[] = [
  {
    id: "start",
    text: "You wake up in a dark forest.  You see a path leading north and a path leading east.  What do you do?",
    choices: [
      {
        text: "Go north.",
        nextSceneId: "northPath",
      },
      {
        text: "Go east.",
        nextSceneId: "eastPath",
      },
    ],
  },
  {
    id: "northPath",
    text: "You walk north and find a small cottage.  The door is open.",
    choices: [
      {
        text: "Enter the cottage.",
        nextSceneId: "cottageInside",
      },
      {
        text: "Continue north.",
        nextSceneId: "northFurther",
      },
    ],
  },
  {
    id: "eastPath",
    text: "You walk east and encounter a wolf.  It growls at you.",
    choices: [
      {
        text: "Run away.",
        nextSceneId: "runAway",
      },
      {
        text: "Fight the wolf.",
        nextSceneId: "fightWolf",
      },
    ],
  },
  {
    id: "cottageInside",
    text: "You enter the cottage and find a warm fire and a table with food.  You feel safe.",
  },
  {
    id: "northFurther",
    text: "You continue north and eventually find your way out of the forest.",
  },
  {
    id: "runAway",
    text: "You run away and escape the wolf, but you are lost.",
  },
  {
    id: "fightWolf",
    text: "You try to fight the wolf but are quickly defeated.",
  },
];

This is a basic example, but it demonstrates how to structure your story data. You can expand on this by adding more scenes, choices, and even variables to track the player’s progress.

Creating the Story Logic

Now, let’s write the core logic for our interactive story. We need a way to:

  • Keep track of the current scene.
  • Display the scene text and choices to the user.
  • Handle user input (choice selection).
  • Update the current scene based on the user’s choice.

Add the following code to `src/index.ts`:

// ... (Interfaces and story data from previous sections)

let currentSceneId: string = "start"; // The ID of the current scene

// Function to get a scene by its ID
function getScene(id: string): Scene | undefined {
  return story.find((scene) => scene.id === id);
}

// Function to display the current scene
function displayScene() {
  const scene = getScene(currentSceneId);

  if (!scene) {
    console.error("Scene not found: " + currentSceneId);
    return;
  }

  // Display the scene text
  const textElement = document.getElementById("story-text") as HTMLElement;
  if (textElement) {
    textElement.textContent = scene.text;
  }

  // Display the choices
  const choicesElement = document.getElementById("choices") as HTMLElement;
  if (choicesElement) {
    choicesElement.innerHTML = ""; // Clear previous choices

    if (scene.choices) {
      scene.choices.forEach((choice, index) => {
        const button = document.createElement("button");
        button.textContent = choice.text;
        button.addEventListener("click", () => {
          currentSceneId = choice.nextSceneId;
          displayScene();
        });
        choicesElement.appendChild(button);
      });
    }
  }
}

Let’s break down this code:

  • currentSceneId: This variable stores the ID of the current scene. It’s initialized to “start”.
  • getScene(id: string): Scene | undefined: This function takes a scene ID as input and searches the story array for a scene with that ID. It returns the scene if found, or undefined if not.
  • displayScene(): This function is the heart of our story logic. It does the following:
    • Gets the current scene using getScene().
    • Checks if the scene exists. If not, it logs an error.
    • Updates the text content of an HTML element with the ID “story-text” to display the scene’s text.
    • Clears any existing choices.
    • If the scene has choices, it creates buttons for each choice.
    • Adds an event listener to each button. When a button is clicked, the currentSceneId is updated to the ID of the next scene, and displayScene() is called again to refresh the display.

Creating the HTML Structure

Now, let’s create the HTML structure for our interactive story. Create an `index.html` file in the root of your project and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Interactive Story</title>
  <link rel="stylesheet" href="style.css">  <!-- Link to your CSS file -->
</head>
<body>
  <div class="container">
    <div id="story-container">
      <p id="story-text"></p>  <!-- Where the story text will be displayed -->
      <div id="choices"></div>  <!-- Where the choices (buttons) will be displayed -->
    </div>
  </div>
  <script src="dist/index.js"></script>  <!-- Link to your compiled JavaScript file -->
</body>
</html>

This HTML structure includes:

  • A `<title>` element for the page title.
  • A link to a CSS file (`style.css`), which we’ll create later for styling.
  • A `<div>` with the ID “story-container” to hold the story content.
  • A `<p>` element with the ID “story-text” to display the story text.
  • A `<div>` with the ID “choices” to display the choices as buttons.
  • A link to the compiled JavaScript file (`dist/index.js`).

Adding Basic Styling with CSS

Let’s add some basic styling to make our story look a little nicer. Create a `style.css` file in the root of your project and add the following CSS:

body {
  font-family: sans-serif;
  background-color: #f0f0f0;
  margin: 0;
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh; /* Make sure the body takes at least the full viewport height */
}

.container {
  width: 80%;
  max-width: 800px;
  background-color: white;
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}

#story-text {
  margin-bottom: 20px;
  font-size: 1.1em;
}

#choices {
  display: flex;
  flex-direction: column;
}

button {
  padding: 10px 15px;
  margin-bottom: 10px;
  border: none;
  background-color: #007bff;
  color: white;
  border-radius: 4px;
  cursor: pointer;
  font-size: 1em;
  transition: background-color 0.2s ease;
}

button:hover {
  background-color: #0056b3;
}

This CSS provides basic styling for the body, container, story text, and choices (buttons).

Compiling and Running Your Code

Now, let’s compile our TypeScript code and run the application.

1. **Compile the TypeScript code:** Open your terminal and run the following command in your project directory:

tsc

This will compile your TypeScript code (`src/index.ts`) into JavaScript (`dist/index.js`).

2. **Open `index.html` in your browser:** Navigate to your project directory in your file explorer and double-click the `index.html` file to open it in your web browser. You should see the first scene of your interactive story, with the choices available.

3. **Interact with the story:** Click the buttons to make choices and progress through the story. You should see the story text and choices update based on your selections.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • **Typographical Errors:** Typos in your scene IDs, choice text, or variable names can lead to errors. Double-check your code for any typos. TypeScript’s strict type checking should help catch these errors during compilation.
  • **Incorrect File Paths:** Make sure the file paths in your HTML (e.g., for the CSS and JavaScript files) are correct. Incorrect paths will prevent the CSS from being applied or the JavaScript from running.
  • **Missing or Incorrect IDs in HTML:** The JavaScript code relies on HTML elements with specific IDs (e.g., “story-text”, “choices”). Make sure these IDs match the IDs used in your JavaScript code.
  • **Incorrect `tsconfig.json` Configuration:** Incorrect settings in your `tsconfig.json` file can lead to compilation errors or unexpected behavior. Review the settings carefully. Make sure the outDir, rootDir, and module options are set correctly.
  • **Not Compiling the TypeScript:** Remember to compile your TypeScript code using tsc whenever you make changes. If you don’t compile, the changes won’t be reflected in the browser.
  • **Uncaught Errors in the Console:** Open your browser’s developer console (usually by pressing F12) to check for any error messages. These messages can provide valuable clues about what’s going wrong.
  • **Incorrect Event Listener Logic:** Make sure the event listeners are correctly attached to the buttons and that the currentSceneId is being updated correctly.

Enhancements and Next Steps

This tutorial provides a foundation for building interactive stories. Here are some ways you can enhance it:

  • **Add More Scenes and Choices:** Expand your story with more scenes, choices, and branching paths.
  • **Implement Conditional Logic:** Use `if/else` statements to create more complex scenarios where choices are influenced by previous actions or variables.
  • **Introduce Variables:** Add variables to track the player’s progress (e.g., health, inventory) and use them to affect the story.
  • **Add Styling:** Improve the visual appearance of your story with more CSS styling.
  • **Include Images:** Add images to the scenes to enhance the user experience.
  • **Implement Local Storage:** Use local storage to save the player’s progress so they can resume the story later.
  • **Add Sound Effects:** Incorporate sound effects to make the story more immersive.
  • **Use a Framework:** Consider using a JavaScript framework (like React, Vue, or Angular) to manage the UI and story logic more efficiently, especially for larger, more complex stories.

Key Takeaways

In this tutorial, we’ve learned how to create a simple interactive story using TypeScript, HTML, CSS, and JavaScript. We’ve covered the basics of defining story elements, handling user input, and displaying content dynamically. This project demonstrates how TypeScript can be used to build interactive web applications and gives you a solid foundation for further exploration. Remember to break down complex problems into smaller, manageable steps, and test your code frequently. This approach will greatly improve your development efficiency and reduce the frustration often associated with coding.

FAQ

Here are some frequently asked questions:

  1. **Can I use a different module system in `tsconfig.json`?** Yes, you can. The `module` setting in `tsconfig.json` specifies the module system to use. Common options include “commonjs”, “esnext”, “amd”, and “umd”. The choice depends on your project’s requirements. For modern web development, “esnext” or “es2020” (or later) is often preferred as it supports the latest ES module features.
  2. **How do I debug my TypeScript code?** You can debug your TypeScript code using your browser’s developer tools. First, compile your TypeScript code to JavaScript. Then, open the developer tools in your browser (usually by pressing F12) and go to the “Sources” tab. You can then set breakpoints in your JavaScript code and step through it line by line. Many code editors also have built-in debugging support.
  3. **How can I deploy my interactive story online?** You can deploy your interactive story online by hosting the HTML, CSS, and JavaScript files on a web server. You can use a service like Netlify, GitHub Pages, or Vercel. These services typically allow you to deploy your project with just a few clicks.
  4. **What is the difference between an interface and a class in TypeScript?** An interface defines a contract for the structure of an object. It specifies the properties and methods that an object must have. A class is a blueprint for creating objects. It can implement interfaces and provide concrete implementations for the properties and methods defined in the interfaces. Interfaces are primarily used for type checking and ensuring that objects conform to a specific structure, while classes are used to create objects with specific behavior and data.

Building interactive stories is a fun and rewarding way to learn about web development and TypeScript. The skills you’ve acquired here can be applied to many different projects, including games, educational applications, and more. Continue experimenting, exploring new features, and refining your skills. The possibilities are truly endless.

More posts