Basic Tweego Setup
If you want to use Tweego v1.x, you'll want to switch to the
tweego-1branch of this repo.
This is the basic setup I use for creating Tweego projects. It's here so I can clone it when I need it, but you may find it useful, too.
For information on why you may want to use this repo, look here.
Note: Before publishing a story, you'll want to change the ifid in the
project/twee/compiler-options.twee file. If you delete it and try to build, Tweego will spit out a new one for you.
You'll need NodeJS and Tweego installed. Click the links to find my step-by-step instructions (with pictures) on how to do this on Windows systems. You will need to combine my instructions with a bit of Googling to get these working on other OSes. You may also wish to globally install Gulp (v4.0.0 or later), but this is optional.
After getting all that squared away, clone or download this repo. Open a command prompt and navigate to the repo's root directory (where the
package.json file is) and run the command
npm install. This may take a couple of minutes, just let it go. After that, everything should be ready to go.
There are four main folders that you'll be working with here. The first is the
dist folder. When you compile your project, it will get sent here as
dist/index.html. If you have external resources using relative links, like fonts, sounds, or images, you'll want to put them in here.
project/scripts folders entirely.
src/scripts folder, and make sure they have the extension
.js. Place your CSS files in the
src/styles folder and make sure they have the extension
.css. Files in these folders will be concatenated, minified, (for JS) transpiled, and (for CSS) autoprefixed, then sent to the
project folder to be picked up by Tweego. Also, only JavaScipt files in the
src/scripts folder will be linted when you run the linter.
src/modules folder allows you to add scripts, styles, fonts, and more directly to the document's
<head>. Things like Google analytics scripts, web libraries, and favicon code will go here. Code included in this way is not processed and is simply included as-is.
vendor folder is a place to put code that comes from other people. For example, if you were using an add-on from the SugarCube site, or one of my custom macros, you'd paste the CSS and JS files in here. You can mix them together; you don't need to use seperate folders for the CSS and JS files.
Finally, there's the
head-content.html file. You can add HTML code to your project's
<head> using this file. If you don't need it, just leave it blank.
The following scripts are run from the command line. Simply navigate to the project's root directory and type in the appropriate command. Note that windows is weird, and some commands require you to type
-win after them to get them to work on Windows systems. However, on Windows systems you also get a collection of batch files to run the scripts for you, so it all works out.
npm config set tweego-setup:format NAME: You can use this command to set which format Tweego should use to compile. By default, it's SugarCube 2. You need to enter the format name as you would to Tweego, so it's based on what you have the format called on your computer. For example,
npm config set tweego-setup:format harlowe-2would probably change the format to Harlowe v2.1.0.
npm run buildor
npm run build-win: Packages up all your CSS and JS code, then compiles the project and opens it in your default browser. You'll need to use the second version on Windows systems.
npm run testmodeor
npm run testmode-win: As
npm run build, but compiles your story in test mode.
npm run tweegobuildor
npm run tweegobuild-win: This command only runs the Tweego portion of the build process, so files from
srcaren't added in. Useful for building faster when you're only working on TwineScript.
npm run lintor
Usage (batch files - Windows only)
If you're on a Windows OS, a number of batch files are included to run these scripts for you without you needing to open a command prompt or (shudder) type things. These are useless to you on other operating systems and can safely be deleted.
npm run build-winfor you.
npm run testmode-winfor you.
format.bat: Lets you quickly see what formats Tweego has access to and change between them. Roughly equivalent to
npm config set tweego-setup:format NAMEbut more user-friendly.
npm run lint-jsfor you.
npm run lint-cssfor you.
src/config.json file contains configuration options you may want to alter. It looks like this:
minify: set this to
falseif you don't want your scripts to be minified.
transpile: if you write code in ES6 syntax, it is automatically transpiled to ES5 giving you better browser support. you can shut this feature off. note that doing so may cause the minifier to stop working.
minify: set this to
falseif you don't want your CSS to be minified.
autoprefix: vendor prefixes will be automatically added for you to maximize browser support. you can shut this off if you want to.
The first four options here tell the build process where to find your scripts and styles. You can change the locations of your folders around using these options. You can also change these options to arrays of strings that resolve to individual file paths to load your code in a specific order--the default order is whatever your OS uses (usually alphanumeric).
The second chunk of options allows you to change where built scripts should be put and what their file names should be.
A list of target browsers, using browserlist-style queries, that you want to target. This effects what the transpiler and autoprefixers do. The defaults set here are copied directly from SugarCube's browserlist, to maintain parity and avoid giving up any browser support, but you may want to change this.