Fix: Use standalone mode for Appwrite Sites (modclean issue)

[josiah-nelson]

Problem Diagnosed

After adding debug logging (PR #113), we discovered the real issue:

✅ Environment detection WORKS - correctly identifies Appwrite mode
✅ Build creates standard .next output as intended
❌ Appwrite's modclean removes 7,558 files including the next package
❌ When npm start runs next start, the command doesn't exist → timeout

Build Log Evidence

[next.config.ts] Detected deployment mode: appwrite
[next.config.ts] Will use output: DEFAULT (no standalone)
✓ Compiled successfully

> postbuild
> if [ -d .next/standalone ]; then ... fi

[open-runtimes] Bundling for SSR started
MODCLEAN Version 2.1.2
FILES/FOLDERS DELETED: Total: 7558

Root Cause

Standard Next.js builds require the next package at runtime to execute next start. However:

1. Appwrite's build process runs modclean after building
2. modclean aggressively removes development dependencies
3. This includes removing the next package from node_modules
4. Result: next start command not found, server never starts

Standalone mode bundles everything into server.js with zero external dependencies, making it immune to modclean.

Solution

Always use output: 'standalone' for all deployment modes:

// Before (conditional)
...(isAppwrite ? {} : { output: 'standalone' }),

// After (always)
output: 'standalone',

Why This Works

Build Type	Runtime Deps	modclean Impact	Result
Standard	Needs next package	❌ Removes next	Breaks
Standalone	Zero deps (self-contained)	✅ No impact	Works

Configuration Changes Required

Appwrite Console (manual update needed):

• Output directory: .next → .next/standalone

Why Docs Say "Don't Set Output"

Appwrite's documentation states:

Next.js: Ensure you don't set output in the next.config.js

However, in practice:

• The docs may be outdated
• May refer to a different runtime implementation
• modclean makes standard builds impossible
• Standalone is the only reliable option

Testing

After this change:

1. Build will create .next/standalone/server.js
2. modclean will run but won't affect standalone bundle
3. npm start will execute the self-contained server
4. Site should respond at https://app.sfplib.com/

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @josiah-nelson, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements a crucial fix for Next.js applications deployed on Appwrite Sites by enforcing the use of Next.js's standalone output mode. This modification ensures that the build process generates a self-contained application bundle, effectively bypassing an issue where Appwrite's modclean utility would remove essential runtime dependencies, leading to application startup failures. The change guarantees that Next.js applications remain functional and robust within the Appwrite deployment environment.

Highlights

• Next.js Configuration Update: The frontend/next.config.ts file has been modified to consistently set output: 'standalone' for all Next.js builds, removing the previous conditional logic that excluded Appwrite deployments.
• Problem Resolution: This change directly addresses a critical issue where Appwrite's modclean utility would inadvertently remove the next package from node_modules, preventing Next.js applications from starting correctly after deployment.
• Enhanced Deployment Robustness: By forcing standalone output, Next.js applications become self-contained, bundling all necessary dependencies into a single server.js file. This makes them immune to dependency removal by modclean and ensures reliable execution on Appwrite Sites.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly identifies and resolves a critical deployment issue on Appwrite Sites by consistently using the Next.js standalone output mode. The analysis of the modclean problem is thorough, and the code change in next.config.ts is the right solution. However, the PR is incomplete because it does not update the project's own deployment documentation (docs/APPWRITE_SITES_DEPLOYMENT.md), which now contains incorrect instructions that will lead to deployment failures. I have added a comment highlighting the necessary documentation update. Once that is addressed, this PR will be a solid improvement.

[gemini-code-assist]

While this change to enforce output: 'standalone' is the correct fix for the Appwrite deployment issue, this pull request is incomplete as it introduces a discrepancy with the project's deployment documentation. The docs/APPWRITE_SITES_DEPLOYMENT.md file still instructs users to set the Appwrite 'Output Directory' to out, which is incorrect for standalone mode and will cause deployments to fail. The documentation must be updated as part of this change to specify .next/standalone as the output directory to align with this code change.