Your first application

Before you start

The goal is a small application you can recognise and test at every stage: Hello cApp, a counter with Add one and Reset. Start without a backend, account, model, wallet or Sidecar. Add a capability only after the application itself works.

Use a configured cApp authoring environment on a Windows computer for the full local workflow. Installed cApp must have its own working services; a browser-based authoring workspace needs its deliberately connected local services. The public documentation and Showroom are not that environment and do not install it for you.

Have a writable source folder, a plain-text editor and the prerequisites reported for your chosen package target. The example needs no Node build command or dependency installation. Windows packaging needs its Windows native toolchain; Android packaging additionally needs Android/JDK/SDK tooling. Android deployment covers tool checks and emulator setup. Do not install every optional capability to complete this guide.

Already have a frontend? First confirm its ordinary browser entry or production build works, then use that source folder in step 1. A backend-only repository is not an interchangeable substitute for this frontend example.

Make one complete source file

Create an empty folder named hello-capp. Save the following as index.html, not index.html.txt, in that folder. Keep the folder outside cApp's own generated output directories.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Hello cApp</title>
  <style>
    body { margin: 0; padding: 24px; font: 18px/1.5 system-ui, sans-serif; }
    main { max-width: 32rem; margin: 2rem auto; }
    h1 { overflow-wrap: anywhere; }
    .controls { display: flex; flex-wrap: wrap; gap: 12px; }
    button { font: inherit; min-height: 44px; padding: 8px 16px; cursor: pointer; }
    button:focus-visible { outline: 3px solid currentColor; outline-offset: 3px; }
    output { font-size: 2rem; font-weight: bold; }
  </style>
</head>
<body>
  <main>
    <h1>Hello cApp</h1>
    <p>A small application with no network or account requirement.</p>
    <p>Count: <output data-capp-test-id="hello-count" aria-live="polite">0</output></p>
    <div class="controls">
      <button type="button" data-capp-test-id="hello-add">Add one</button>
      <button type="button" data-capp-test-id="hello-reset">Reset</button>
    </div>
    <p data-capp-test-id="hello-status" role="status">Ready.</p>
    <p>This example keeps its count in memory. Reloading starts at zero.</p>
    <noscript>Enable JavaScript to use the counter.</noscript>
  </main>
  <script>
    (() => {
      const countOutput = document.querySelector('[data-capp-test-id="hello-count"]');
      const status = document.querySelector('[data-capp-test-id="hello-status"]');
      const add = document.querySelector('[data-capp-test-id="hello-add"]');
      const reset = document.querySelector('[data-capp-test-id="hello-reset"]');
      let count = 0;
      add.addEventListener('click', () => {
        if (count >= 99) { status.textContent = 'Limit reached. Reset to start again.'; return; }
        count += 1;
        countOutput.textContent = String(count);
        status.textContent = 'Added one.';
      });
      reset.addEventListener('click', () => {
        count = 0;
        countOutput.textContent = '0';
        status.textContent = 'Reset to zero.';
      });
    })();
  </script>
</body>
</html>

Open the file in an ordinary browser. Add one should display 1; Reset should restore 0. Reloading should also restore 0: this is deliberately not a persistence or sync example. The file contains no external assets, requests or SDK imports. This check establishes the source interaction, not a cApp compile or native installation.

1. Create a project and choose the component

Open Projects, choose + New project, name it Hello cApp, and use an application version such as 0.1.0. Set Initial source to your hello-capp folder, or leave it empty and link the folder in Build. Leave Hosted runtime backend empty for this example.

Open the new project's card and confirm the Active project, then follow Build → Source & package. In Application source, select Project folders and check App to build. When the source is not already linked, use + Folder, choose your folder, give it the All role and choose Refresh app. Do not add the same folder a second time.

A component is one independently compilable application. Use a separate component for an independent second app; Frontend, Backend and Shared roots are parts of the same app. Linking reads your folder without moving it. Inspect the selected component and the detected index.html entry before compiling. Projects and source explains these controls in detail.

2. Compile and inspect the actual product

Review Version and Runtime backend before compilation; this app needs no backend origin. Choose Compile once and follow the reported stages. The normal action prepares source, analyses it and finalises an immutable release; the separate low-level controls are not extra required steps.

The result should identify a usable, renderable application, not a diagnostic or compatibility-only surface. In preview, confirm Hello cApp, then repeat Add one → 1 → Reset → 0. A wrapper around an unsupported-source report is not this result.

In Selected release, use Copy reference and retain the capp:compiler-release:sha256:… value, then Continue to package. This release identifies the compiled content; it is not a Windows installer or an Android package. If you edit the HTML, refresh and compile again to see the new source. Selecting an older release intentionally retains its older content.

3. Add only the capabilities you need

No Sidecar is required for the counter. Leave optional capabilities unselected on the first pass. This makes a source or packaging failure easier to separate from a capability setup issue.

After that first successful package, open Choose sidecars or Library with the intended application active. Use Add to app, then Configure, for one appropriate capability. Selection/configuration changes save to that application's packaging state; adding a component is not the same thing as installing a new package on a device.

For example, Test Runner can exercise the counter's stable data-capp-test-id selectors within its admitted app surface. It uses a virtual cursor, not desktop-wide input. Build with Sidecars covers package IDs, readiness, application interfaces and cleanup. Do not paste a provider credential into this example or silently replace an unavailable component with another provider.

4. Package for the target

Choose Windows or Android, review the selected release, app name, application ID, version, icon, signing setup and effective capabilities, then start that target's Build action. The package must consume the selected immutable release, not uncompiled edits in the linked folder.

Inspect Output for the actual target files and their verification/provenance information. Compilation, source materialisation and package preparation are not completed native builds. If a toolchain stage fails, correct that prerequisite and retry packaging the same release rather than recompiling unchanged HTML.

On Windows, use the actual installer/output exposed by the build controls. On Android, Install & run on an emulator opens Deploy with the chosen output; verify the target device and artifact before installing. Follow Android deployment rather than assuming an arbitrary AAB is directly installable or that a phone and emulator need the same architecture.

Keep the same application ID and signing identity for an update intended to retain existing data. Do not uninstall or clear storage as a routine update step. The counter intentionally has no saved data, so it cannot prove data-preserving updates for a more complex application.

5. Test outside the development environment

Launch the installed application. Check its title, first screen, readable layout and Add one → 1 → Reset → 0 using the target's actual mouse/keyboard or touch controls. Close and reopen it: the in-memory count should start at 0. The counter should work without a backend or network connection.

Stop unrelated development helpers that might mask missing packaged services, without disabling services actually owned by the installed application. If you added a Sidecar, test its installed entry point and unavailable/disabled state separately. A working counter does not prove native wallet support, inference or backend authentication.

Keep the compiler release reference, package filename/hash, target/version and observed result together. Compile, package and release covers provenance; Test an application surface covers repeatable app tests. A Showroom listing is optional and belongs to the separate publishing workflow.

Make one change without losing the known result

Change the heading in your source to Hello cApp again, set the next application version, refresh the source and compile a new release. Confirm the changed heading in the new preview. The previous release should still identify its original content; it is not relabelled by the edit.

Package the new release and test the update using the same intended application identity and signing key. A docs update or a source-file edit alone does not update the installed app. Only packaging settings or a repaired toolchain can normally be retried against the existing release; compiler-owned source, version or backend planning changes require a new compile.

Troubleshooting the first run

What you have proved

You have checked one source interaction, a usable compiler release and the matching installed target package. Those are three distinct results. You have not yet qualified a backend, a permissioned Sidecar, persistence, synchronization or a public deployment. Continue with SDK installation or Sidecar composition one capability at a time.