AppStudio Project File Format

AppStudio Project File Format

This page describes the on-disk format of an AppStudio project. It is intended for developers who want to understand, inspect, or programmatically manipulate project files.

Overview

An AppStudio project is stored as a directory whose name ends with .appstudio. Everything belonging to the project lives inside that directory. The project is made up of plain JSON text files and optional code files, so you can open them in any text editor.

Directory Layout

MyApp.appstudio/
├── MyApp.project              ← Main project file (JSON)
├── forms/                     ← One sub-directory per form
│   ├── Form1/
│   │   ├── Form1.json         ← Form definition (JSON)
│   │   ├── Form1.bas          ← Form BASIC code (optional)
│   │   ├── Form1.js           ← Form JavaScript code (optional)
│   │   └── Elements/
│   │       ├── Button1.json   ← Control definition (JSON)
│   │       ├── TextArea1.json
│   │       └── ...
│   ├── Form2/
│   │   └── ...
│   └── ...
├── properties/                ← Build / deployment configuration
│   ├── config.xml             ← Apache Cordova / VoltBuilder config
│   ├── manifest.json          ← Progressive Web App (PWA) manifest
│   ├── package.json           ← Electron build config
│   ├── electronMain.js        ← Electron entry-point script
│   └── style.css              ← Project-wide CSS (optional)
└── .gitignore

The only required file is the .project file. All other files are created automatically as you add forms and controls in the IDE.

The Project File (*.project)

The project file is a JSON file at the root of the .appstudio directory. Its name matches the project name (e.g. MyApp.project).

Top-level (Project object)

Property	Type	Description
"!type"	String	Always "Project". Identifies this object as the root project.
version	Integer	Project file format version. Current value is 8.
language_version	Integer	BASIC language version. Current value is 8.
id	String	Project identifier. Usually the project name without spaces.
filename	String	Absolute path to the .appstudio directory (set at runtime; empty in the file).
libraries	Array of String	Libraries included in the project, e.g. ["BASIC"].
script	String	Project-level code that runs before any form code.
children	Array	Contains exactly one Page object (inline, not a file reference).
deploy_protocol	String	Deployment protocol: "ftp", "sftp", or "local".
deploy_server	String	FTP/SFTP server hostname.
deploy_port	String	Server port, default "21".
deploy_userName	String	Login username for FTP/SFTP.
deploy_password	String	Login password (stored in plain text — keep the file private).
deploy_path	String	Remote path to upload files to.
deploy_local	Boolean	If true, deploy to a local folder instead of a server.
deploy_localPath	String	Local folder path used when deploy_local is true.
deploy_global	Boolean	If true, use global (shared) deployment settings.
phonegap_email	String	Adobe PhoneGap Build account e-mail (legacy; prefer VoltBuilder).
phonegap_password	String	Adobe PhoneGap Build password (legacy).
phonegap_auth_token	String	Adobe PhoneGap Build API token (legacy).
cached_js	String	Cached compiled JavaScript for the project (managed by the IDE).
cached_js_script_hash	String	MD5 hash of the source used to generate cached_js.
cache_dirty	Boolean	When true, the IDE will recompile the project before the next run.
expanded_pmp	String or null	Remembers which nodes are expanded in the Project Manager panel.

Page object (inside children)

A project contains exactly one Page object. It is stored inline in the .project file (not as a separate file).

Property	Type	Description
"!type"	String	Always "Page".
id	String	Page / app identifier. Typically the same as the project name.
title	String	App title shown in the browser tab and home screen.
description	String	Short description of the app.
version	String	App version string, e.g. "1.0.0".
copyright	String	Copyright notice included in the built app.
appPublisher	String	Publisher name.
language	String	Default code language: "BASIC" or "JavaScript".
firstform	String	id of the form shown when the app starts.
defaultformsize	String	Design canvas size, e.g. "320x460".
fontFamily	String	Default font family, e.g. "helvetica".
icon	String	Path to the app icon (192 × 192 px PNG), e.g. "nsb/images/512.png".
iconAndroid	String	Path to the Android-specific icon (192 × 192 px PNG).
splashscreen	String	Path to the splash screen image.
BootstrapTheme	String	Bootstrap CSS theme name, e.g. "bootstrap".
theme	String	jQuery Mobile theme letter, e.g. "a".
style	String	Additional CSS applied to the whole app.
background	String	CSS background colour or value for the page body.
backgroundimage	String	URL or path to a background image.
enableBrowserArrows	String ("true"/"false")	When "true", the browser Back / Forward buttons navigate between forms.
enableNiceLinks	String ("true"/"false")	When "true", the URL bar reflects the current form name.
contentSecurityPolicy	String	Value of the Content-Security-Policy meta tag (leave blank for the default policy).
manifest	String or null	Inline app-cache manifest content (legacy).
manifestFile	String	Name of the manifest file, e.g. "appcache".
manifestName	String	Name attribute of the manifest, e.g. "OfflineApp".
disablePWA	String	Set to "true" to suppress the PWA service-worker and manifest.
FastClick	String ("true"/"false")	Enables the FastClick library to remove the 300 ms tap delay on mobile.
stopOnError	String ("true"/"false")	When "true", unhandled runtime errors stop the app and display a message.
obfuscation	String	Set to "true" to obfuscate the compiled JavaScript on build.
obfuscatorSettings	String (JSON)	JSON string containing javascript-obfuscator options.
eslintRules	String or null	Custom ESLint rules as a JSON string (JavaScript projects only).
useStrict	String	Set to "true" to add "use strict" to the generated JavaScript.
extraheaders	String or null	Raw HTML inserted into the <head> of the generated page.
styleheaders	String or null	Additional CSS inserted into the <head> of the generated page as a <style> block. When non-empty this content is also stored in the external file properties/style.css.
script	String or null	Page-level code shared across all forms.
voltAppId	String	App ID registered on VoltBuilder.
voltDomain	String	Custom domain used for VoltBuilder builds.
phoneGapBuildID	String	Adobe PhoneGap Build app ID (legacy).
phoneGapVersion	String	Target PhoneGap / Cordova version (legacy).
phoneGapLanguages	String	Comma-separated language codes, e.g. "en".
phoneGapStatusBarColor	String	Status bar background colour, e.g. "#000000".
phoneGapStatusBarStyle	String	Status bar style: "lightcontent" or "default".
phoneGapStatusBarOverlay	String ("true"/"false")	Whether the status bar overlays the web view.
electronDevTools	String ("true"/"false")	Open DevTools automatically when running in Electron.
electronMain	String or null	Override content of properties/electronMain.js.
electronPackage	String or null	Override content of properties/package.json.
configxml	String or null	Override content of properties/config.xml.
viewportFit	String	Viewport fit value for notched phones, e.g. "cover".
rtl	String	Set to "true" to switch the app to right-to-left layout.
homescreenTitle	String	Short name shown below the icon on the device home screen.
browserwarnmsg	String	Message shown when the app is opened in an unsupported browser.
onresize	String	Code called when the browser window is resized.
onorientationchange	String	Code called when the device orientation changes.
onvisibilitychange	String	Code called when the page visibility changes.
children	Array	External references to each form JSON file.

Form Files

Each form is stored in its own sub-directory under forms/. The JSON file shares the name of the directory:

forms/
└── Form1/
    ├── Form1.json       ← Form definition
    ├── Form1.bas        ← BASIC code for this form (optional)
    ├── Form1.js         ← JavaScript code for this form (optional)
    └── Elements/
        ├── Button1.json
        └── TextArea1.json

Form object properties

Property	Type	Description
"!type"	String	Always "Form".
id	String	Unique identifier of this form. Used in code to refer to the form and its controls.
width	Integer	Form width in pixels at design time.
height	Integer	Form height in pixels at design time.
designWidth	Integer	Width of the design canvas (may differ from width when using responsive layout).
designHeight	Integer	Height of the design canvas.
left	Integer	Left position offset in pixels.
top	Integer	Top position offset in pixels.
position	String	CSS position value, typically "absolute".
language	String	Code language for this form: "BASIC" or "JavaScript".
fullScreen	String ("true"/"false")	When "true", the form fills the entire screen.
modal	String ("true"/"false")	When "true", the form is displayed as a modal dialog.
openMode	String	Transition used when opening the form (e.g. "none", "fade", "slide").
scrolling	String ("true"/"false")	Enables iScroll-based scrolling inside the form.
scroll_options	String	iScroll options as a comma-separated key:value string.
theme	String	jQuery Mobile theme letter for this form (overrides the page theme).
background	String	CSS background colour or value.
backgroundimage	String	Path or URL to a background image.
style	String	Additional inline CSS for the form container.
class	String	Additional CSS class names for the form container.
borderColor	String	Border colour (design-time only).
borderStyle	String	Border style (design-time only).
borderWidth	String	Border width (design-time only).
action	String	HTML action attribute when the form is rendered as a <form> element.
method	String	HTML method attribute ("get" or "post").
onsubmit	String	Code called when the form is submitted.
onshow	String	Code called when the form becomes visible.
onhide	String	Code called when the form is hidden.
onresize	String	Code called when the form is resized.
onkeypress	String	Code called on a key-press event anywhere on the form.
setFocusID	String	id of the control that receives focus when the form opens.
parentForm	String	id of another form that this form is visually nested inside.
HTML	String or null	Raw HTML injected at the top of the form (advanced use).
attributes	String	Additional HTML attributes added to the form element.
locked	Boolean	When true, controls on this form cannot be moved in the designer.
script	String or null	Form code. null when code is stored in the external .bas or .js file.
cached_js	String or null	Cached compiled JavaScript (managed by the IDE).
cached_js_script_hash	String or null	MD5 hash used to detect when recompilation is needed.
cache_dirty	Boolean	true when the cached JavaScript is out of date.
children	Array	External references to each element JSON file.

Element Files

Each control (button, text box, label, etc.) on a form is stored as a separate JSON file in the Elements/ sub-directory of the form.

Common properties

All controls may share the following properties. Not all properties are used by all elements - they may only have the ones they actually use. They may also have additional properties, which are defined in the Toolbox Files for that control.

Property	Type	Description
"!type"	String	The control type, e.g. "Button_bs4", "Textarea_bs4", "Label_bs4". The suffix _bs4 indicates a Bootstrap 4 control.
id	String	Unique identifier of this control within the form. Used in code to access the control at runtime (e.g. Button1.value).
left	Integer	Left position in pixels, relative to the form.
top	Integer	Top position in pixels, relative to the form.
width	Integer or String	Width in pixels, or "auto".
height	Integer or String	Height in pixels, or "auto".
right	String	CSS right value, typically "auto".
bottom	String	CSS bottom value, typically "auto".
position	String	CSS position mode: "absolute", "relative", or "static".
hidden	String	Set to "true" to hide the control at runtime.
disabled	String	Set to "true" to disable user interaction.
class	String	Additional CSS class names.
style	String	Additional inline CSS styles.
display	String	CSS display value (overrides the default).
color	String	Foreground / text colour (CSS value).
backgroundColor	String	Background colour (CSS value).
fontFamily	String	Font family (CSS value).
fontSize	String	Font size (CSS value, e.g. "14px").
fontStyle	String	Font style: "italic", "normal", etc.
fontWeight	String	Font weight: "bold", "normal", etc.
mAll, mTop, mBottom, mLeft, mRight	String	CSS margin shorthand and individual sides.
pAll, pTop, pBottom, pLeft, pRight	String	CSS padding shorthand and individual sides.
borderColor, borderStyle, borderWidth	String	CSS border properties.
script	String	Control-level code (usually blank; form-level code is preferred).
cached_js	String	Cached compiled JavaScript for this control (managed by the IDE).
cached_js_script_hash	String	MD5 hash used to detect when recompilation is needed.
children	Array	Nested controls (empty for most control types).
expanded_pmp	String or null	Expansion state in the Project Manager panel (IDE only).

Bootstrap appearance properties

Controls based on Bootstrap have these additional properties.

Property	Type	Description
appearance	String	Bootstrap contextual class, e.g. " btn-secondary", " btn-primary", " btn-danger".
size	String	Bootstrap size modifier, e.g. " btn-sm", " btn-lg".
outline	String	Set to "outline-" to use an outlined (hollow) button style.
blockLevel	String	Set to "true" for a full-width block button.
grouping	String	Used to group controls into a Bootstrap button group.
groupStyle	String	Style applied to the button group container.

Popover properties

Most controls support an optional Bootstrap popover.

Property	Type	Description
popStyle	String	Popover style: "popover" or "tooltip".
popTitle	String	Popover title text.
popBody	String	Popover body text.
popPosition	String	Popover position: "top", "bottom", "left", "right", or blank for automatic.
popClose	String	How the popover closes: "hover" or "click".

Badge properties

Property	Type	Description
badge	String	Badge text. Leave blank to hide the badge.
badgeAppearance	String	Bootstrap contextual class for the badge, e.g. " badge-info".

Common event handlers

Event handler properties contain a string that is the name of the function to call (e.g. "Button1_onclick()"). The actual function body is written in the form's code file.

Property	Event
onclick	User clicks or taps the control.
onmousedown	Mouse button pressed over the control.
onmouseup	Mouse button released.
onmousemove	Mouse pointer moves over the control.
onmouseout	Mouse pointer leaves the control.
ontouchstart	Touch begins on the control.
ontouchmove	Touch moves while in contact with the control.
ontouchend	Touch ends on the control.
onresize	Control is resized.

Selected control-specific properties

Button (Button_bs4)

Property	Type	Description
value	String	Button label text.
icon	String	Set to "true" to show an icon inside the button.
iconTitle	String	Icon CSS class (e.g. a Bootstrap Icons or Font Awesome class name).
ChangeForm	String	id of a form to navigate to when the button is clicked (shortcut — no code required).
toggleControl	String	id of a control to toggle the visibility of when the button is clicked.

Text Area (Textarea_bs4)

Property	Type	Description
value	String	Initial text content of the text area.
placeholder	String	Grey hint text displayed when the text area is empty.
rows	String	Number of visible text rows.
maxlength	String	Maximum number of characters allowed.
readonly	String	Set to "true" to make the text area read-only.
required	String	Set to "true" for HTML5 form validation.
autocomplete	String	"on" or "off".
autocorrect	String	"on" or "off" (mobile browsers).
autocapitalize	String	"on" or "off" (mobile browsers).
spellcheck	String	"true" or "false".
header	String	Label text shown above the text area.
footer	String	Help text shown below the text area.
validation	String	Validation rule expression.
inputmode	String	HTML5 inputmode attribute, e.g. "numeric".
align	String	Text alignment: "left", "center", "right".
name	String	HTML name attribute for form submission.
headerCols	Integer	Bootstrap grid column width of the label (0 = full width label above).
valueCols	Integer	Bootstrap grid column width of the input field.
onchange, onclick, onfocus, onfocusout, onkeypress, onkeyup	String	Event handler function names.
oncopy, oncut, onpaste	String	Clipboard event handler function names.

Code Files

BASIC code files (.bas)

When a project uses the BASIC language, form code is stored in a plain-text file with the same name as the form but with the .bas extension (e.g. Form1.bas). The file sits in the same directory as the form's JSON file.

The file contains standard AppStudio BASIC functions. Event handlers follow the naming convention ControlID_eventname():

Function Button1_onclick()
  MsgBox "Thanks for clicking!"
End Function

Function Form1_onshow()
  TextArea1.value = "Form is now visible."
End Function

JavaScript code files (.js)

JavaScript projects use .js files with the same naming convention. The syntax is standard JavaScript:

function Button1_onclick() {
  alert("Thanks for clicking!");
}

Inline script

Code can alternatively be stored inline in the JSON file itself, in the script property of the Form or control object. The IDE stores code externally by default; the script property in the saved file is null when an external file is used.

The properties/ Directory

The properties/ directory holds template files used when building the app for different deployment targets. These files contain {placeholder} tokens that AppStudio replaces with actual project values at build time.

config.xml

Apache Cordova / VoltBuilder configuration file. Used when building native mobile apps.

Common placeholders: {id}, {title}, {version}, {description}, {copyright}, {icon}, {phoneGapSplash}, {phoneGapBuildCounter}, {phoneGapStatusBarColor}, {phoneGapStatusBarStyle}, {phoneGapStatusBarOverlay}.

manifest.json

Progressive Web App (PWA) manifest. Tells the browser how to install the app on a home screen.

Common placeholders: {title}, {description}, {icon}.

package.json

Electron build configuration used when packaging the app as a desktop executable.

Common placeholders: {title}, {version}, {description}, {id}.

electronMain.js

The Electron main-process entry point. Launched by package.json when the desktop app starts.

Common placeholders: {appwidth}, {appheight}, {title}.

style.css

The project-wide CSS file. Its content is inserted into the <head> of the generated page as a <style> block, after all library stylesheets. Use it to define custom styles, override theme defaults, or declare @font-face rules that apply across the whole app.

This file is the external representation of the Page object's styleheaders property. The IDE creates or updates style.css automatically whenever the Project CSS editor is saved. If the property is empty, the file is omitted.

To edit this file from within AppStudio, open the Project menu and choose Open Project CSS.

Example:

/* Custom styles for MyApp */
body {
  background-color: #f5f5f5;
}

@font-face {
  font-family: MyFont;
  src: url('MyFont.ttf');
}

External References

To keep individual files small and manageable, forms and controls are stored in separate files. A parent object refers to a child file using an External reference object:

{
  "!type": "External",
  "file": ["forms", "Form1", "Form1.json"]
}

The file array represents a path relative to the .appstudio directory: each element is one path segment. The example above refers to the file forms/Form1/Form1.json.

External references appear in:

• The Page's children array — pointing to each form's JSON file.
• A Form's children array — pointing to each element's JSON file in the Elements/ sub-directory.

When AppStudio loads a project it resolves all External references recursively, producing a single in-memory object tree. When saving, the tree is split back into individual files.

Complete Example

The following annotated listing shows all the files in a minimal "Hello World" project.

HelloWorld.project

{
  "!type": "Project",
  "version": 8,
  "language_version": 8,
  "id": "HelloWorld",
  "libraries": ["BASIC"],
  "script": "",
  "children": [
    {
      "!type": "Page",
      "id": "HelloWorld",
      "title": "HelloWorld",
      "description": "Use a button to put up a Hello World message.",
      "version": "1.0.0",
      "copyright": "copyright 2025 ABC Company",
      "language": "BASIC",
      "firstform": "Form1",
      "defaultformsize": "320x460",
      "fontFamily": "helvetica",
      "icon": "nsb/images/512.png",
      "iconAndroid": "nsb/images/192.png",
      "BootstrapTheme": "bootstrap",
      "theme": "a",
      "children": [
        {
          "!type": "External",
          "file": ["forms", "Form1", "Form1.json"]
        }
      ]
    }
  ]
}

forms/Form1/Form1.json

{
  "!type": "Form",
  "id": "Form1",
  "language": "BASIC",
  "width": 375,
  "height": 667,
  "designWidth": 375,
  "designHeight": 667,
  "fullScreen": "true",
  "children": [
    { "!type": "External", "file": ["forms", "Form1", "Elements", "Button1.json"] },
    { "!type": "External", "file": ["forms", "Form1", "Elements", "TextArea1.json"] }
  ]
}

forms/Form1/Elements/Button1.json

{
  "!type": "Button_bs4",
  "id": "Button1",
  "value": "Click me!",
  "left": 98,
  "top": 194,
  "width": 113,
  "height": "auto",
  "appearance": " btn-secondary",
  "size": " btn-sm",
  "onclick": "Button1_onclick()"
}

forms/Form1/Elements/TextArea1.json

{
  "!type": "Textarea_bs4",
  "id": "TextArea1",
  "value": "Here is a simple Hello World app.",
  "placeholder": "Enter text here",
  "left": 45,
  "top": 48,
  "width": 239,
  "height": "116"
}

forms/Form1/Form1.bas

Function Button1_onclick()
  MsgBox "Thanks for clicking!"
End Function

See Also

• Toolbox_Files — describes the toolbox definition files that specify the available control types and their default properties.
• VoltBuilder — how to build native iOS and Android apps from an AppStudio project.
• Electron — how to package an AppStudio project as a Windows or macOS desktop app.