finally.js v1.0.1

Finally.js - Effortless FTP Deployments for Your Website

Supported Platforms

Table of Contents 📝

• Features and Benefits
• Use Cases

• Friendly request to users

• Installation - Step-by-Step Guide

• Usage

• License

• Contributing to Our Project

• Website

• Contact Information

• Credits

Features and Benefits ✨

• 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.

Use Cases ✅

• 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.

🙏🏻 Friendly Request to Users

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. 🌍💖

Installation - Step-by-Step Guide 🪜

Prerequisites

• Step 1: Ensure you have Node.js installed on your local machine or environment.

Installation

• Step 2: Add Finally.js to your project:

  npm install finally.js

Configuration (optional⚠️)

• Step 3: Create a finally.c.json file in the root of your project.

• Step 4: Add the following content to the finally.c.json file:

  {
    "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, and FTPPASS_ENV_VAR with the respective environment variables for your FTP server.

Usage

Running the Deployment Script

• 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.

CLI Options

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.

Advanced Usage

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 --secure

In this example:

• Files from the dist folder will be uploaded to the /public_html directory on the FTP server.
• The folders test and devfiles will 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.

Example Deployment Process

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 dist folder:

  mkdir sample-project
  cd sample-project
  mkdir dist
  echo "Hello World" > dist/index.html

• Step 2: Create Configuration File (optional⚠️): In the sample-project directory, create a finally.c.json file 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

GitHub Actions Integration

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 --secure

Key Points:

• The workflow triggers on every push to the main branch.
• 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.

License ©️

This project is licensed under the MIT.

Contributing to Our Project 🤝

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!

Website 🌐

npmjs - finally.js

Contact Information

For any questions, please reach out via hello@darsan.in or LinkedIn.

Credits 🙏🏻

Credit to patrickjuchli for the basic-ftp npm package.

Topics