Finally.js is a Node.js tool for seamlessly deploying website files to an FTP server. It automates the process of collecting files from a specified directory and ensures secure authentication through environment variables. Ideal for developers looking to streamline their deployment process, Finally.js can be effortlessly integrated with GitHub Actions for automated deployments.
- Automated File Collection: Gathers files from a specified directory for deployment.
- Secure Authentication: Utilizes environment variables for secure FTP authentication.
- GitHub Actions Integration: Easily integrates with GitHub Actions for CI/CD pipelines.
- Efficient Deployment: Simplifies the process of deploying website files to an FTP server.
- Customizable Directory: Allows specification of the directory from which files are collected.
- Node.js Compatible: Built on Node.js, making it easy to integrate with existing Node.js projects.
- Automated Website Deployment: Deploy your website files to an FTP server automatically after each commit.
- Secure FTP Uploads: Use secure environment variables to authenticate FTP uploads without exposing credentials.
- CI/CD Integration: Seamlessly integrate with GitHub Actions to automate deployment in your CI/CD pipeline.
- Custom Directory Deployment: Deploy files from any directory you specify, giving you control over what gets uploaded.
Every star on this repository is a sign of encouragement, a vote of confidence, and a reminder that our work is making a difference. If this project has brought value to you, even in the smallest way, please consider showing your support by giving it a star. ⭐
"Star" button located at the top-right of the page, near the repository name.
Your star isn’t just a digital icon—it’s a beacon that tells us we're on the right path, that our efforts are appreciated, and that this work matters. It fuels our passion and drives us to keep improving, building, and sharing.
If you believe in what we’re doing, please share this project with others who might find it helpful. Together, we can create something truly meaningful.
Thank you for being part of this journey. Your support means the world to us. 🌍💖
- Step 1: Ensure you have Node.js installed on your local machine or environment.
-
Step 2: Add Finally.js to your project:
npm install finally.js
-
Step 3: Create a
finally.c.jsonfile in the root of your project. -
Step 4: Add the following content to the
finally.c.jsonfile:{ "host": "FTPSERV_ENV_VAR", "port": 21, "user": "FTPUSER_ENV_VAR", "password": "FTPPASS_ENV_VAR", "secure": false } -
Step 5: Replace
FTPSERV_ENV_VAR,FTPUSER_ENV_VAR, andFTPPASS_ENV_VARwith the respective environment variables for your FTP server.
-
Step 1: Run the deployment script to upload your files:
finally -b dist -r /public_html
-
Step 2: The script will connect to the FTP server and upload all files from the specified local directory (
dist) to the target directory (/public_html) on the server.
Finally.js provides a variety of CLI options to customize your deployment process:
-b, --basePath <path>: Specifies the local base path of the files to upload. This option is required.-r, --remoteBasePath <path>: Specifies the remote base path on the FTP server. This option is required.-i, --ignorePattern <patterns...>: Defines patterns to ignore during the upload. The default is["./node_modules/**", ".git/**"].-n, --ftpVerbose: Enables verbose mode for FTP, which provides detailed logs during the upload process.-h, --host <host>: Sets the FTP server host. By default, it is fetched from the configured environment variable.-p, --port <port>: Sets the FTP server port. By default, it is fetched from the configuration.-u, --user <user>: Sets the FTP server username. By default, it is fetched from the configured environment variable.-a, --password <password>: Sets the FTP server password. By default, it is fetched from the configured environment variable.--secure: Enables a secure FTP connection (FTPS). By default, it is determined by the configuration.
You can pass additional options to Finally.js for more advanced deployments:
npx finally -b dist -r /public_html -i test/** devfiles/** --ftpVerbose -h ftp.example.com -p 21 -u exampleuser --password examplepass --secureIn this example:
- Files from the
distfolder will be uploaded to the/public_htmldirectory on the FTP server. - The folders
testanddevfileswill be ignored during the upload. - FTP verbose mode is enabled to provide detailed logs.
- Custom FTP server credentials (
host,user,password) are provided directly through the CLI.
Here's a step-by-step example of how to deploy files using Finally.js:
-
Step 1: Setup a Sample Project: Create a sample project directory and add some files to a
distfolder:mkdir sample-project cd sample-project mkdir dist echo "Hello World" > dist/index.html
-
Step 2: Create Configuration File (optional
⚠️ ): In thesample-projectdirectory, create afinally.c.jsonfile with your FTP server details:{ "host": "FTPSERV_ENV_VAR", "port": 21, "user": "FTPUSER_ENV_VAR", "password": "FTPPASS_ENV_VAR", "secure": false } -
Step 3: Deploy Files: Run the deployment command to upload your files to the FTP server:
npx finally -b dist -r /public_html
To automate deployments with Finally.js using GitHub Actions, add the following workflow file (.github/workflows/deploy.yml) to your repository:
name: FTP Deployment
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4.1.7
- name: Set up Node.js
uses: actions/setup-node@v4.0.3
with:
node-version: "20"
- name: Install Finally.js
run: npm install finally.js
- name: Deploy to FTP
env:
FTP_SERVER: ${{ secrets.FTP_SERVER }}
FTP_USERNAME: ${{ secrets.FTP_USERNAME }}
FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
run: finally -b dist -r /public_html -h ${{ secrets.FTP_SERVER }} -u ${{ secrets.FTP_USERNAME }} --password ${{ secrets.FTP_PASSWORD }} --port 21 --secureKey Points:
- The workflow triggers on every push to the
mainbranch. - The workflow installs Node.js and Finally.js, checks out the code, and then runs the deployment command.
- FTP credentials are securely stored as secrets in your GitHub repository settings and referenced in the workflow file.
By following these steps, you can set up automated deployments directly from your GitHub repository to your FTP server.
This project is licensed under the MIT.
We’re always open to contributions and fixing issues—your help makes this project better for everyone.
If you encounter any errors or issues, please don’t hesitate to raise an issue. This ensures we can address problems quickly and improve the project.
For those who want to contribute, we kindly ask you to review our Contribution Guidelines before getting started. This helps ensure that all contributions align with the project's direction and comply with our existing license.
We deeply appreciate everyone who contributes or raises issues—your efforts are crucial to building a stronger community. Together, we can create something truly impactful.
Thank you for being part of this journey!
For any questions, please reach out via hello@darsan.in or LinkedIn.
Credit to patrickjuchli for the basic-ftp npm package.
- ftp deployment
- node.js deployment tool
- automated website deployment
- github actions integration
- ftp server
- secure authentication
- ci/cd pipeline
- web development
- ftp upload
- environment variables
- node.js
- website deployment
- automated deployment
- ftp automation
- ftp tool
- deploy website
- file transfer
- web hosting
- ftp integration
- ftp client