Trackstr Client

Development

We must use 127.0.0.1 instead of localhost when connecting to ActivityWatch and API Server because then we can intercept requests in order to debug them.

API Client

An API client is generated via openapi-ts from an Open API definition. Run the server instance locally and invoke npm run openapi-ts to regenerate.

ActivityWatch Integration

This application integrates with ActivityWatch, an open-source time-tracking and productivity tool. The integration allows the app to:

1. Track window activity (which applications and websites you use)
2. Track when you're AFK (away from keyboard)
3. Collect data for productivity analysis

How It Works

• On startup, the app checks if ActivityWatch is running by querying its API.
• If ActivityWatch is already running on the machine, the app will use the existing instance and will not start the bundled version.
• If ActivityWatch is not running, the app will attempt to start it automatically using the bundled binary for your operating system.
• If the binary cannot be started, the application will log an error but will continue to function without activity tracking.

Bundled Binaries (Linux & Windows)

• Linux & Windows: The app bundles the aw-qt binary for both platforms and will use the bundled version if ActivityWatch is not already running.
• The binaries are they are included with the application.

Development Workflow

• During development, you should put activitywatch in the project root. It is ignored in the GIT and won't be commited.
• You can run npm run download-activitywatch-binaries which will download Windows and Linux binaries in the folder which will be ignored by git, and running npm start will automatically start activitywatch with those binaries.

Production/Release Workflow

• In production builds, the app will use the bundled ActivityWatch binary if ActivityWatch is not already running on the system.
• If you want to override the default behavior (for example, to use a system-installed ActivityWatch), you can set the ACTIVITY_WATCH_EXECUTABLE environment variable in your .env file:

# For Windows (example)
ACTIVITY_WATCH_EXECUTABLE=C:\\Program Files\\activitywatch\\aw-qt.exe

# For macOS (example)
ACTIVITY_WATCH_EXECUTABLE=/Applications/ActivityWatch.app/Contents/MacOS/aw-qt

# For Linux (example)
ACTIVITY_WATCH_EXECUTABLE=/usr/bin/aw-qt

Troubleshooting

• For custom setups or troubleshooting, set the ACTIVITY_WATCH_EXECUTABLE environment variable to the full path of your ActivityWatch binary.
• The application will log errors if it cannot find or start ActivityWatch, but will continue to run without activity tracking.

---

Tanstack Query for easier communication with APIs

The client can be generated by running npm run openapi-ts - please note that the server must be running locally on port 5000 to work atm.

For demonstration purposes, it has been implemented on the Users page.

Release Process

This project uses semantic-release for automated versioning and release management. When code is pushed to the main branch, the workflow automatically:

1. Analyzes commit messages to determine the next version number
2. Updates the version in release/app/package.json
3. Generates release notes based on commit messages
4. Creates a new CHANGELOG entry
5. Creates a Git tag for the new version
6. Builds the application for all platforms
7. Creates a GITEA release and attaches build artifacts

Commit Message Format

This project follows Conventional Commits for commit messages. The format determines how versions are incremented:

• fix: - patches a bug (PATCH version bump)
• feat: - adds a new feature (MINOR version bump)
• feat!:, fix!:, etc. - introduces breaking changes (MAJOR version bump)
• docs:, style:, refactor:, test:, chore: - no version bump

Examples:

fix: resolve issue with screenshot capture
feat: add dark mode support
feat!: redesign user interface with breaking API changes
docs: update README with new instructions

Release Assets

The following assets are automatically attached to each release:

• Windows: TrackStr Setup x.x.x.exe (NSIS installer)
• macOS: TrackStr-x.x.x.dmg (macOS disk image)
• Linux: TrackStr-x.x.x.AppImage (Linux AppImage)

All build files are placed in the release/build directory during the build process.

Prerequisites for Automated Releases

For the automated release workflow to function properly:

1. A GITEA token with appropriate permissions must be set up as a repository secret named TOKEN.

   • Go to your GITEA user settings
   • Generate a new access token with repo permissions
   • Add it as a secret in your repository settings

2. Node.js version 22 or higher is required for building the application due to dependencies requiring newer Node.js versions.

3. Wine must be installed on the build server to enable cross-platform Windows builds.

4. Follow the Conventional Commits format for your commit messages to ensure proper versioning.

Manual Release

In case you need to manually create a release:

1. Run npx semantic-release --no-ci locally to create a new version and tag
2. Run npm run package to build the application
3. Create a new release in GITEA manually and upload the assets from the release/build directory

License

MIT © Electron React Boilerplate