Suggested Configurations
When you create a new project or visit the Build Pipeline page, DeployHQ inspects your repository for manifest files (package.json, composer.json, Gemfile, go.mod, and others) and offers build commands, language versions, and config files tailored to the framework it finds. Detection runs automatically after each successful clone and pull, so as your project evolves, the suggestions stay current.
How detection works
After DeployHQ pulls a fresh copy of your repository, it scans the working copy for known manifest files and records the framework it identifies. The result is stored against your project and used in three places:
- Suggested build commands on the Build Pipeline page
- Suggested config files when you add a new server
- Runtime version banner when your project's runtime requirement does not line up with the build environment
Detection looks at the contents of manifest files -- not just their presence -- so child frameworks are identified correctly. For example, a Laravel project using Statamic, Lunar, Twill, October, or Winter is matched to its specific child stack rather than the generic Laravel template.
If detection cannot find a manifest it recognises, no suggestions are offered and you can configure the build pipeline manually as usual.
Applying suggested configurations
When suggestions are available, you will see them on the Build Pipeline page above the existing build commands. Each suggestion shows the proposed command, the description, and the language version it expects.
Click Apply to add a suggestion to your project. You can edit the command afterwards just like any other build command -- the suggestion is a starting point, not a fixed recipe.
If you would rather configure the build pipeline manually, click Skip to dismiss the suggestions. You can revisit them at any time from the same page.
Runtime version mismatch banner
If your project declares a runtime requirement (for example, a Ruby version in Gemfile, a Node version in package.json engines, or a PHP version in composer.json) and the selected build environment does not satisfy that requirement, DeployHQ shows a warning banner at the top of the Build Pipeline page.
There are two shapes of mismatch:
- Series mismatch: your project allows a range (for example,
ruby '~> 3.4') but the build environment is on a different series (3.3.x). The banner suggests switching to a build environment series that satisfies your constraint. - Version pin mismatch: your project pins to an exact version (for example,
ruby '3.4.2') but the build environment is pinned to a different version. The banner suggests updating either your project or the build environment so the pins agree.
The banner appears only when there is a real mismatch. Loose constraints that the build environment already satisfies do not raise a warning.
Supported frameworks
Detection covers the most common stacks across the major ecosystems:
| Ecosystem | Detected frameworks |
|---|---|
| PHP | Laravel, Symfony, Statamic, October CMS, Lunar, Twill, Winter CMS, Drupal, WordPress, Craft CMS |
| Node | Next.js, Nuxt, Remix, SvelteKit, Astro, Gatsby, Vue, React, Angular, Eleventy, Hexo |
| Ruby | Ruby on Rails, Jekyll |
| Python | Django, projects using requirements.txt |
| .NET | ASP.NET and other projects using *.csproj files |
| Static site | Hugo |
| Tooling | Composer, Yarn, npm, Webpack, Gulp, Maven, Pip |
The list grows over time. If your stack is not detected yet, the suggestions section simply does not appear and you can configure your build pipeline manually.
When detection does not run
Detection runs after every successful clone or pull. It does not run if:
- The repository has not been pulled successfully yet -- pulling the repository for the first time triggers the first detection.
- The repository contains no recognisable manifest files at the root or in conventional locations.
- The manifest files are present but their contents do not match any known framework signature.
In any of these cases, the Build Pipeline page falls back to a manual workflow with no suggestions and no banner. You can always add build commands and choose a build environment as before.
Further information
For background on how build commands run, see the Build Pipelines article. For details on selecting and pinning language versions, see Language versions.