Creating an AFrame typescript project without using the CLI

We recommend using the aframe-typescript-toolkit CLI for expediency and ease of use. However, if you'd like to create an aframe-typescript-toolkit project from scratch. This section is for you. The code discussed below is similar to the one component template generated by the CLI in the README.

An A-Frame typescript component is created in three steps:

1. Setup your project
2. Define and register a component or system class
3. Use your custom component in a local A-Frame project using webpack
4. Export your custom component via GitHub & RawGit to be shared and used in other A-Frame projects

Project Setup

We recommend creating a directory with the following structure:

new-component
│   README.md
│   package.json    
│   webpack.config.js
│   tsconfig.json
│
└───src
    │   index.html
    │   index.ts

We will discuss how to setup your webpack and other configurations below. You can refer to the example projects for webpack, node scripts, and tsconfig boilerplate or use a custom setup depending on your needs.

Install A-Frame Typescript Toolkit into your project

yarn add aframe-typescript-toolkit

Create and register your component (or system) class

1. import ComponentWrapper and EntityBuilder into index.ts

import { ComponentWrapper, EntityBuilder } from "aframe-typescript-toolkit"

2. Define a schema for your component's data

interface NewComponentSchema {
    readonly color: string
}

3. Define your component class by extending ComponentWrapper

export class NewComponent extends ComponentWrapper<NewComponentSchema> {

    constructor() {
        super("new-component", {
            color: {
                type: "string",
                default: "colorless",
            }, 
        })
    }
    
    init() {
       
    }
}

4. Define component behavior

Now you can define the visual aspects or behavior of your component. We'll add an entity on init using Entity Builder.

    ...
    init() {
        const entityColor = this.el.getAttribute("color")
        EntityBuilder.create("a-text", {
            id: "color-text",
            value: entityColor || this.data.color,
            color: entityColor || "black",
            position: "-1 1.25 0",
        }).attachTo(this.el)
    }

5. Register your component

at the bottom of your index.ts file, after defining your component register it so it can be used in your A-Frame scene.

new NewComponent().register()

Using your Custom Component Locally

1. Compiling typescript with Webpack

To use your custom component locally, your typescript file must be compiled into javascript. Webpack is a convenient tool to accomplish this. You can configure your 'webpack.config.js` to suit your needs. However, if you're new to webpack or don't require a custom setup, you can copy the webpack config from one of our examples, or use the webpack.config.js generated by the CLI.

See the webpack documentation for more details.

2. Include and Install all dependencies

Like the webpack config, you might find it easier to copy the dependencies from one of our examples into your package.json file.

Then run npm install to install all dependencies

3. Add build scripts

If you have copied the webpack config and dependencies, you can also copy the build scripts from the example into your project's package.json file.

    ...
    "scripts": {
        "build": "cross-env NODE_ENV=production webpack --config ./webpack.config.js  --progress --profile --color --display-error-details --display-cached --bail",
    ...

4. Make a build

In your command line, run npm build to create a production build using webpack.

You will see ./dist directory has been created inside of your root directory (or otherwise if you used a custom webpack configuration).

5. Create an index.html A-Frame Scene

In your index.html file (in the root directory), include the scripts for A-Frame as well as your custom component (/index.js). The way we have configured our example projects creates a copy of index.html into the /dist folder which is ultimately served. So our index.html file points to /index.js. Yours might point to /dist/index.js depending on your setup.

In the A-Frame scene, create an entity using your component by including the component's name defined in the constructor. In this example, the component's name is new-component.

<html>
    <head>
        <!-- This is the A-Frame CDN -->
        <script src="https://aframe.io/releases/0.8.0/aframe.min.js"></script>
        
        
        <!-- This is the file you created in the previous step -->
        <script type="text/javascript" src="/index.js"></script>
    </head>
    <body>
        <a-scene embedded antialias="true">
            <a-sphere 
                color="red" 
                position="-1 2 -5"
                new-component 
            >
            </a-sphere>
            <!-- 'new-component' is the name we gave our component in the constructor-->
            <a-box
                position="2 3 -10"
                new-component
            >
            </a-box>
            <a-sky color="#ECECEC"></a-sky>
            <a-light position="0 10 0" color="white" type="point"></a-light>
        </a-scene>
    </body>
</html>

6. View your A-Frame Scene

Locally serve your project to see what you've created. If you were following the examples, you can run the command yarn start to serve the project to localhost:3000. This server will listen to any changes you make to the /src directory

Alternatively, you can run a command like python -m SimpleHTTPServer 3000 from your root directory and then visit your web browser at http://localhost:3000/src. Using this method , remember you'll have to rebuild your project using npm build to see any changes to index.ts.