Netlify: Builds, Previews and Deploys

Netlify

Netlify connects application builds and deployment with services such as preview environments, routing, and serverless functions. The useful starting point is a reproducible build and a clear release boundary: which files are deployed, which code runs on a server, and which event changes production.

A successful deploy is evidence that the platform accepted an artifact. It is not proof that a deep link works, a private variable stayed private, or the application can recover from a failed backend change. Put those checks in the workflow deliberately.

TL;DR

Declare build and output expectations in a version-controlled configuration where appropriate.
Distinguish a deploy preview from production, including its data, credentials, and external integrations.
Keep build-time variables separate from server runtime secrets and values intentionally embedded in public assets.
Use supported functions and framework integrations rather than assuming static hosting can execute arbitrary server behavior.
Test routing directly, including missing pages and API paths, before adding a broad fallback.
Plan release, rollback, and data compatibility together; restoring frontend output does not undo a database migration.

Quick Example

For a small fictional static site with a build script that produces dist/, this complete netlify.toml declares its build and a preview-specific non-secret label:

The example assumes package.json already provides the build command and that dist/ is the correct output. It does not create the application, install a framework adapter, configure secrets, or deploy anything. APP_ENV is a public-safe label; it is not an access control.

Netlify's file-based configuration reference documents build fields and deploy contexts. Confirm the effective base directory, build command, publish directory, and framework integration in the real project. A correct field name pointing to the wrong directory still deploys the wrong result.

Core Concepts

Build output and runtime behavior are different

A build prepares files and may also generate function or framework artifacts. Static assets can be delivered without running an application server per request. A request-time feature needs an appropriate runtime path supported by the platform and the application's integration.

Netlify's functions overview documents serverless handlers and supported conventions. Check the relevant language, API, limits, and framework adapter rather than treating every Node.js application as a function automatically.

Deploy previews create another environment

Netlify's Deploy Previews guide describes unique URLs associated with pull or merge requests. That can give reviewers a concrete application to inspect before release.

The preview still needs an environment design. Decide which database, identity callbacks, storage, email service, and payment sandbox it uses. A separate URL does not isolate a shared production backend, and an obscure URL is not authentication for sensitive preview content.

Variables have a context and a scope

The environment-variable guide distinguishes deploy contexts and scopes such as builds and functions. Configure values for the code that needs them and inspect precedence rules when the same name exists in several places.

Also inspect what the build does with a value. A secret available during a build may become public if the application writes it into JavaScript or generated HTML. The variable's storage location does not control the confidentiality of the resulting browser artifact.

Map the deployment path before connecting automation

This is an operating checklist, not a statement that every control is available on every plan. Verify current project settings, platform documentation, and edition-specific requirements before relying on a feature for release governance.

Build a preview that proves something useful

Choose a representative review flow. For a documentation site, check a new page, navigation, redirects, a missing route, and asset loading. For an application, include sign-in, one authorized data read, a failure state, and an interaction with a sandboxed external service.

Identify the revision displayed in the preview and the backend it uses. A reviewer can otherwise approve frontend changes while unknowingly exercising stale API behavior. If preview data is reset between builds, tell reviewers how to obtain repeatable test accounts or fixtures.

Review access for untrusted contributions. Build scripts execute code from the source tree and can read the credentials made available to that build. Do not assume a pull request is safe merely because its intended change looks like content. Use the host's supported trust and approval controls, and keep sensitive integrations out of untrusted execution.

Capture useful failures as well as successes. Check that a build error blocks the intended release path and leaves enough diagnostics. Verify whether changing configuration requires a new build or another action. The objective is an understandable workflow, not a green badge detached from the application.

Make routing and functions explicit

Netlify documents redirects and rewrites. A redirect tells the client to visit another URL; a rewrite serves another destination behind the current URL. Choose the behavior that matches navigation and application expectations.

A broad single-page-application fallback can make deep links work, but it can also return HTML where an API client expected JSON or hide missing pages behind success responses. Test existing assets, nested routes, API paths, and unknown paths independently. Keep framework-generated routing rules in mind before adding another competing rule.

For functions, define input validation, authentication, authorization, time budgets, and failure responses. Test browser and server consumers through the actual routing layer. A handler that works when called directly may behave differently after redirects, rewrites, or framework dispatch.

Do not embed administrative credentials in browser code to simplify a function call. The server boundary should reduce the client's privilege, not simply hide a highly privileged operation behind a convenient endpoint.

Release and recovery need a data story

Read the project's applicable deploy management documentation and verify who can change the production artifact. Distinguish the branch that triggers a build from the step that makes output serve production traffic.

Prepare a recovery exercise with a known compatible artifact. If a release also changes a database, event format, or external integration, determine whether an older frontend and function version can still operate against it. Reverting static files cannot restore deleted records or reverse an incompatible schema by itself.

Evaluate costs from the actual workload: build activity, traffic, functions, storage, and other used services. Consult current product limits and pricing when estimating; this page intentionally provides no fixed quota or price promise.

Best Practices

Keep effective configuration visible

Record which settings come from repository files and which come from the project. Review precedence when troubleshooting. A small configuration file is useful only if the team understands what overrides it.

Separate preview privileges

Use data and credentials appropriate to review work. Verify identity callbacks and external destinations. Review secret availability for untrusted builds before enabling integrations.

Verify the deployed journey

Check direct navigation, status codes, assets, functions, and failure messages on the produced environment. Build success is one step in that verification, not its conclusion.

Common Mistakes

Publishing the source directory

Bad: Point publish at a convenient folder without inspecting the build output.

Correct: Confirm the actual generated artifact and framework integration, then test the result at a direct URL.

Treating preview URLs as isolated data

Bad: Let every preview use production administrative credentials and mutable production data.

Correct: Design the preview backend and trust model explicitly, with only the privileges its review flow needs.

Treating rollback as database recovery

Bad: Assume restoring prior frontend output undoes every release side effect.

Correct: Plan data compatibility, migration recovery, and external effects alongside artifact recovery.

FAQ

Is Netlify only for static websites?

No. It also provides functions and supported framework integrations. Check whether the particular request-time feature and operating requirements fit the documented platform path.

Are deploy previews production releases?

They use a separate preview URL and workflow. Their safety and usefulness still depend on configured data, credentials, access, and external integrations.

Can a build variable become public?

Yes, if the build embeds it in browser assets or generated pages. Keep secrets out of those artifacts and verify the framework's variable-exposure conventions.

Does the example configuration deploy this project?

No. It is a bounded configuration example for an existing fictional static application. No project connection or publication action is performed by this article.